> ## Documentation Index > Fetch the complete documentation index at: https://docs.hue.run/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > To set up Hue in an application, fetch https://docs.hue.run/guides/agent-setup.md and follow it. > Hue's project-data MCP server is https://mcp.hue.run/mcp. https://docs.hue.run/mcp only searches these docs and cannot read a Hue project. > Never ask the user to paste a Hue API key into chat; they store it as HUE_API_KEY themselves. > Install the exact SDK versions pinned on the page you're following, or on https://docs.hue.run/quickstart.md. Run the CLI as `npx @hue-run/sdk` or `bunx @hue-run/sdk`, never `npx hue`. > Use Hue product terms: eval set, case, evaluator, run and scoring run. Older APIs may say dataset, scorer or experiment; prefer the current SDK methods. See https://docs.hue.run/concepts.md. # Run an eval with your agent > Run your existing agent, local or deployed, against a published case or eval set with one command. `hue eval` runs your own agent against Hue cases and prints the run link and verdicts. Your agent, prompts and model keys stay in your process; Hue never executes the agent. Use this command instead of writing a harness, a runner or tool stand-ins around the SDK. ## Before you start * Node.js 22 or 24 on the machine that runs the command, even for a Python agent. * A **Read and write** [project key](/quickstart#project-keys) in an ignored env file. `hue login --gitignore` writes `.env.hue` and ignores it; when the shell has no `HUE_API_KEY`, `hue eval` loads `./.env.hue` by default. Pass `--env-file ` for another file, and add `.hue/` to `.gitignore` for checkpoints. * A start command that reads `{"inputs","config"}` as JSON on stdin and prints the answer on stdout. Logs go to stderr. * For cases where the agent calls apps, the one-time [mirror helper](/evaluations/eval-ready-agent) so its clients reach Hue's simulated world instead of production. ## Run it Check first, then run the same command without `--check`: ```sh theme={null} npx -y @hue-run/sdk@0.16.0 eval --case "" --command "" --check npx -y @hue-run/sdk@0.16.0 eval --case "" --command "" ``` `--check` resolves the key's project, the selection and its evaluators, and whether cases are answer-only or get a world. It creates no run, world or checkpoint. A published case carries its own evaluators. To run an eval set, use `--set ""` and add `--scorer-version ` for each evaluator; Hue's **Run** snippet for the set includes them. * **One command, one run.** The run holds every selected case: a 100-case eval set is one run with 100 executions. The command prints the `https://app.hue.run/runs/` link once the run exists. * **Let it finish.** Start the command in the background or with a long timeout. If it stops early (Ctrl+C, SIGTERM, a tool timeout or a crash), the run stays open: run the identical command again to resume it from `.hue/eval/`. Finished cases are kept, and an interrupted case runs again, in a fresh world for a world case. After a crash, an answer-only case that was mid-run is reported uncertain instead. If it stops while waiting for Hue's checks, the cases already finished: open the run link instead of rerunning. Never delete that directory to start over. * **Exit codes.** 0 every case passed; 1 a case failed, errored, is inconclusive or is incomplete; 2 usage error; 130 interrupted. * **Compare.** Pass `--baseline ` to see improvements and regressions against an earlier run. ## Answer-only and world cases | Case | What the command receives | What the agent does | | - | - | - | | Answer-only | `HUE_EXECUTION_ID` and case variables, no world | Answers without connecting app clients. | | World | A fresh world: `HUE_WORLD_TOKEN` and one `HUE_SIM__URL` per mirrored app | The helper swaps each app's production URL and credential for the mirror and world token. | The helper fails closed: with an execution but no world token, or a missing mirror URL, a required app connection throws before any request. Outside a Hue eval it returns production values unchanged. `hue eval` removes `HUE_API_KEY` and other Hue credentials from the command's environment unless you pass `--allow-hue-credentials`. ## Local or deployed * **Local, one run:** the one-shot command above. * **Local, launched from Hue:** `hue eval --worker --command ""` registers the agent and runs what the **Run** button or `launch_local_run` starts, one run per launch, until you stop it. * **Deployed:** run the worker beside the deployment with a non-production key and a start command that forwards stdin to the deployed agent and prints its answer. Never put world variables or a **Read and write** key in production configuration. See [`hue eval`](/sdks/cli#run-an-evaluation) for every flag and [simulations](/evaluations/simulations) for how worlds are built and graded. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.