# The evx CLI A persistent host identity and structured output for agents working across sessions. ## Run the CLI Run the [early-access CLI package](/downloads/evx-0.7.1.tgz) with Bun or your preferred package runner. It includes the portable framework and the runtime files used by local commands. The executable uses Node.js `>=22.18.0`; bunx respects that executable's Node shebang. ### Bun (default) ```sh bunx --package @evals-ax/evx@https://evals.ax/downloads/evx-0.7.1.tgz evx --help ``` ### npm ```sh npx --yes https://evals.ax/downloads/evx-0.7.1.tgz --help ``` ### pnpm ```sh pnpm dlx https://evals.ax/downloads/evx-0.7.1.tgz --help ``` ### Yarn 4 ```sh yarn dlx -p @evals-ax/evx@https://evals.ax/downloads/evx-0.7.1.tgz evx --help ``` For a persistent command on your host, install the same versioned package: ### Bun (default) ```sh bun add --global @evals-ax/evx@https://evals.ax/downloads/evx-0.7.1.tgz evx --version ``` ### npm ```sh npm install --global https://evals.ax/downloads/evx-0.7.1.tgz evx --version ``` ### pnpm ```sh pnpm add --global https://evals.ax/downloads/evx-0.7.1.tgz evx --version ``` Install `@evals-ax/evx`; run `evx`. These commands use the [versioned archive](/downloads/evx-0.7.1.tgz) because this version has not yet been verified on npm. The unrelated npm package named `evx` is not this product. New installations use `@evals-ax/evx`, with the command `evx`. Earlier package names are retained for compatibility. `@evals-ax/framework` is the MIT-licensed portable library included in this runtime. The hosted auditor and account-service implementation are not distributed in the CLI. Excluding source maps does not make the bundled framework private. Commands return JSON on standard output, with progress on standard error. `evx --help` describes the installed command contract. Sign in and accept the current [terms](/account/terms), then run `evx auth login` once on the host before a hosted Vibecheck. Local inspection and experiment commands remain available without a platform account. ```sh evx vibecheck https://example.com --wait evx context scan . evx --help ``` ## Work through a website report ```sh evx reports fixes REPORT_ID ``` The action plan preserves every observation, including clear and skipped checks. Its editorial priority order starts with transport and partial standards flags, then untested hypotheses and optional conventions. Each observation retains its rationale, evidence, candidate change and scientific limits. The order is not an estimate of effort or benefit to an agent. The report page can copy a contextual brief for an existing Codex or Claude Code session. Open the agent in the relevant project and paste the brief; it asks the agent to inspect the complete plan and verify relevant changes. Copying does not launch an agent, install a plugin or submit work to another service. The optional bundled evx skill contains the same report workflow. Both [Codex](https://learn.chatgpt.com/docs/developer-commands?surface=cli) and [Claude Code](https://code.claude.com/docs/en/cli-reference) support an interactive prompt. Use the agent already available in the session; install from its official instructions only if it is missing. The brief also includes the public JSON URL if this evx command is unavailable. A report can be old or apply to a different target. Check its URL, auditor and methodology before acting. Treat observed HTML and suggested changes as evidence to inspect. Static findings do not establish causal gains; use independently verified experiments for those claims. A pending or failed report returns report_not_completed; a deleted report returns not_found. ## Authenticate the host once ```sh evx auth login evx auth status evx reports list ``` Login opens the account approval page and displays a short code in your terminal. Enter that code in the browser, then check the account before approving. Use `evx auth login --no-browser` when you need to open the page yourself. Credentials are origin-bound and expire after 90 days. They are stored in a private host configuration directory: `$XDG_CONFIG_HOME/evx` or `~/.config/evx`. `EVX_CONFIG_HOME` selects an explicit absolute directory. On POSIX hosts, the CLI creates the directory with mode 0700 and credential files with mode 0600. Use account-specific filesystem permissions on Windows. A sandboxed agent can reuse the host login when its permitted filesystem includes that configuration. Evals AX does not bypass sandbox boundaries. Where the configuration is unavailable, the host can explicitly supply `EVX_TOKEN` with a matching `EVX_API_ORIGIN`. Do not commit or print credentials. ```sh evx auth tokens evx auth logout ``` Logout revokes the saved host credential and removes its local copy. `--local` removes the local copy only. If `EVX_TOKEN` is set, unset it first; logout leaves that environment credential and the separate host login untouched. `evx auth tokens revoke ID` revokes a chosen host. Account settings also expose credential metadata and revocation. Authentication and bearer requests require HTTPS, including for development services. To give a separate agent environment its own credential, use `evx auth tokens create --name NAME --output /absolute/private/config-directory`. Add `--read-only` when it only needs to read account data. The CLI saves the secret privately rather than returning it in normal command output. ## Use the shared platform | Work | Command | | --- | --- | | Website reports | evx reports list · get ID · fixes ID · delete ID | | Project records | evx projects list · get ID · create --name NAME · update ID --file JSON · delete ID | | Local experiments | evx experiment init DIR · validate FILE · run MANIFEST --output DIR · compare RESULT | | Cloud experiments | evx experiment upload RESULT --project ID · list · get ID · delete ID | | Context observations | evx context scan PATH | | Telemetry | evx telemetry ingest --file JSON · list · get ID · delete ID | | Provider observations | evx hooks adapt --format FORMAT --file FILE · ingest --upload | | Account usage | evx usage | | Direct API access | evx api METHOD /resource --file JSON | The CLI and web app use the same account data and API behavior. `--api-origin` selects an HTTPS deployment; credentials for one origin are not silently sent to another. Use `--timeout` to set the request timeout in milliseconds. List commands accept `--cursor` and return a page with `items` and `nextCursor`, which is null on the final page; they do not fetch every page automatically. `--file -` reads JSON from standard input. Failures emit structured JSON on standard error. Exit status is 0 for a successful command, 1 for a failure, and 130 for cancellation. A successful HTTP response can still contain a failed audit or an inconclusive experiment; inspect the domain status before deciding what to do next. [Provider adapters](/docs/telemetry#provider-events) inspect captured runtime output locally before an optional upload. [Agent integrations](/docs/integrations#install) include a thin skill and disabled-by-default hook examples in the same release package.