CLI reference

Every Evident CLI command, flag, and environment variable.

The evident CLI runs OpenCode locally and connects it to Evident. It is published as @evident-ai/cli and installs a binary named evident.

Install

npm install -g @evident-ai/cli

Or run it directly with npx without installing:

npx @evident-ai/cli@latest <command>

Commands

The CLI has four commands: login, logout, whoami, and run.

evident login

Authenticate with Evident. By default this uses the browser-based device flow: the CLI shows a one-time code and opens your browser to confirm it. Sessions are stored per endpoint, so you can stay signed in to more than one backend at the same time. 

evident login

Options:

  • --token — Use token-based authentication instead of the device flow (for CI/CD); paste a token when prompted.
  • --no-browser — Don't open the browser automatically (visit the URL manually).

evident logout

Remove stored credentials. By default this signs you out of the current endpoint only (the one selected by --endpoint / EVIDENT_API_URL, otherwise production). 

evident logout

Options:

  • --all — Remove stored credentials for every endpoint.

evident whoami

Show the currently authenticated user for the current endpoint.

evident whoami

evident run

Connect to Evident and serve your agent. evident run authenticates, resolves which agent to run, ensures opencode serve is running on loopback, opens the streaming tunnel (which transparently proxies the agent's web surface), and delivers any channel messages (such as Slack) to your local OpenCode. 

# Connect a specific agent
evident run --agent <agent-id>

# Drive a single conversation
evident run --agent <agent-id> --conversation <conversation-id>

# CI: exit after 30s with no work
evident run --agent <agent-id> --idle-timeout 30

Options:

Flag Description
-a, --agent [id] Agent ID to connect to. Optional when EVIDENT_AGENT_KEY is set — the agent is then resolved automatically from the key.
-p, --port <port> OpenCode port. Default: 4096.
-v, --verbose Show detailed request/response information.
-c, --conversation <id> Process only this specific conversation.
--idle-timeout <seconds> Exit after N seconds with no pending work. Useful in CI to avoid polling indefinitely.
--json Output in JSON format. Forces non-interactive mode.

Global flags

These apply to every command and select which backend the CLI talks to. The CLI targets the production Evident platform by default.

Flag Description
--endpoint <url> Evident REST API base URL (e.g. http://localhost:3001). A trailing /v1 is optional — it is added automatically.
--tunnel <url> Tunnel WebSocket URL (e.g. ws://localhost:8787).

Environment variables

Variable Description
EVIDENT_AGENT_KEY An agent key. When set, evident run authenticates as that agent and resolves the agent ID automatically, so --agent is not required. Ideal for CI/CD.
EVIDENT_TOKEN A user token used for authentication, as an alternative to a keychain login from evident login.
EVIDENT_API_URL Override the API base URL (equivalent to --endpoint).
EVIDENT_TUNNEL_URL Override the tunnel relay URL (equivalent to --tunnel).

Precedence

Authentication for run is resolved in this order: EVIDENT_AGENT_KEY → EVIDENT_TOKEN → the credentials stored by evident login.

Backend URLs are resolved per setting: an explicit --endpoint / --tunnel flag wins over the matching environment variable (EVIDENT_API_URL / EVIDENT_TUNNEL_URL), which in turn overrides the production default.

Configuration

Configuration and credentials are stored under:

  • $XDG_CONFIG_HOME/evident/ if XDG_CONFIG_HOME is set
  • otherwise ~/.config/evident/

Credentials are stored per endpoint, so a token is only ever used for the backend that minted it.

Next steps