CLI

The amodal CLI runs an agent locally, executes evals, and manages hosted deployments. It includes the JavaScript runtime and chat UI. The installed binary does not require Node or npm; agent packages and custom frontend builds may need their own toolchain.

Install

On macOS or Linux:

curl -fsSL https://releases.amodalai.com/install.sh | bash

The installer uses curl and tar, installs into ~/.amodal, and adds the command to your PATH. Restart your shell, then run:

amodal --version
amodal login
amodal dev ./path/to/agent

An agent directory must contain amodal.json. Run amodal <command> --help for command options.

Commands

Command	Purpose
`amodal login`	Sign in and select an organization and agent.
`amodal logout`	Remove the stored login session.
`amodal org`	Select the active organization; `--list` lists organizations.
`amodal agent`	Select or create the agent used for local trace attribution and deployment commands; `--list` lists agents.
`amodal gateway`	Resolve the cached model gateway key; `--refresh` mints a fresh key.
`amodal dev [path]`	Start the local runtime and chat UI.
`amodal eval [filter]`	Run evals and report failures.
`amodal connections <action> [name]`	Declare, configure, and authorize named connections.
`amodal corpus index`	Build semantic indexes for reference corpora.
`amodal deploy`	Build the active agent's connected source.
`amodal deploy-status <deploy-id>`	Read deployment status; `--watch` waits for completion.
`amodal promote`	Promote the active deployment from one environment to another.
`amodal rollback`	Activate an earlier deployment.
`amodal deploy-settings`	Read or update deployment settings.
`amodal upgrade`	Install a published CLI version.

Sign In

amodal login

Login opens a browser and stores the resulting session in ~/.amodal/credentials.json with owner-only permissions. It selects an organization and agent, prompting when there are several choices. If the organization has no agent, login automatically creates "Default Agent" for local trace attribution.

Signed-in local runs can use Amodal's model gateway, subject to the selected organization's model access, quota, and billing. Switch the organization or agent with amodal org or amodal agent. Switching organizations also selects an agent in that organization.

If you have a platform token of kind cli, you can sign in without a browser:

amodal login --token "$AMODAL_CLI_TOKEN"

The observer, operator, and admin token kinds do not provide the CLI's organization/agent selection and local telemetry access. For deployment automation with an operator token, use the Deployment API.

Run Locally

amodal dev                          # agent in the current directory
amodal dev ./agent --port 4000      # another directory and port
amodal dev ./agent --open           # also open the chat UI in a browser

The runtime API and chat UI share http://localhost:3847 by default. The local server uses in-memory sessions and stores, so it needs no database and loses local state when it stops. See Session sync for copying conversation history to Amodal.

Choose A Model

Use --model or the MODEL environment variable to choose the model. The CLI infers anthropic for claude-*, google for gemini-*, and an OpenAI-compatible provider for other names. Set --provider or LLM_PROVIDER to override that inference. Flags take precedence over environment variables.

Without overrides, a gateway run uses the platform's configured model. A run using local credentials defaults to google/gemini-3.6-flash.

amodal dev                          # gateway default when signed in
amodal dev --model "$MODEL_NAME"    # a model your route allows

Model availability depends on organization settings and upstream provider access; see Providers.

Gateway Or Provider Keys

With no local key or custom base URL, a signed-in run uses Amodal's gateway. Setting a key for the selected provider uses your credentials instead:

Provider	API key variables
`google`	`GEMINI_API_KEY` or `GOOGLE_API_KEY`
`anthropic`	`ANTHROPIC_API_KEY`
`openai`	`OPENAI_API_KEY`

Put variables in your shell or an uncommitted .env file. The CLI loads .env from the agent directory, then the current directory. Shell variables take precedence; the agent directory takes precedence over the current directory.

An explicit base URL (--base-url, LLM_BASE_URL, or OPENAI_BASE_URL) also selects your own routing. Use --gateway to force the platform gateway or --no-gateway to use local credentials.

Only the selected provider's key affects routing. An unrelated provider key does not disable the gateway. A gateway provider override that differs from the gateway default also needs an explicit model.

If gateway setup fails, the CLI reports the reason and tries the local configuration. Local model calls still require suitable credentials. Check the startup banner to confirm the model and route.

Hot Reload

The watcher reloads root-level agents/, tools/, skills/, hooks/, connections/, knowledge/, stores/, evals/, package.json, and amodal.json. Existing chat sessions keep their history.

Edits inside amodal/ require a server restart. That directory is loaded as agent content but is outside the local watcher's targets.

Edits to the loaded .env files reapply variables and resolve the model again. Invalid bundle edits log a reload error and leave the last working bundle serving. Build output, node_modules/, and other dotfiles do not trigger reloads. Use --no-watch to disable watching.

Scope

Requests without scope_id use the local scope local. Override the default with:

amodal dev ./agent --scope mission-42

A request's own scope_id takes precedence. Local development supplies this scope for agents configured to require one; see amodal.json.

Tracing

Trace export uses your login session and selected agent. It is on by default for gateway runs and opt-in for runs using your own provider key:

amodal dev --no-traces      # disable trace export
amodal dev --traces         # enable it for a run using your own key

The CLI probes trace ingestion at startup. The Traces: exporting to ... banner confirms export is active. It names the platform API base URL; view results in Amodal's Traces page.

The source filter defaults to All, showing local and deployed runs. Select Local to show only local runs. Each exported turn includes model/tool spans, token usage, and cost data.

Session Sync

Local session history can also appear in Amodal's Sessions page. Sync is on by default for gateway runs and opt-in for runs using your own keys:

amodal dev --no-sync-sessions
amodal dev --sync-sessions

Sync copies transcripts to the platform on a best-effort basis. The local in-memory store remains the runtime's working store. Select Local or All on the Sessions page to view synced conversations. amodal eval does not sync its temporary sessions.

Both trace export and session sync need a selected agent in the login organization. A one-off --org override to another organization disables them; use amodal org to switch the stored organization and agent together.

Startup Checks

Startup reports the model, routing, scope, and runtime URL. It also checks:

Provider credentials for the selected model.
Environment references in root-level connections/*/spec.json.
Variables declared in root-level tools/*/tool.json env arrays.
Installed packages declared by package.json and amodal.json.
Trace export readiness and available CLI updates.

The environment scan does not include amodal/connections/ or amodal/tools/. Check those definitions yourself when a connection or tool reports a missing variable.

Dev Options

Option	Description
`[path]`	Agent directory; default `.`.
`--port`	Listen port; default `3847`.
`--host`	Bind address; default `127.0.0.1`.
`--model`, `--provider`	Override the model and provider.
`--base-url`	Use a custom model endpoint.
`--gateway`, `--no-gateway`	Force gateway or local routing.
`--org`	Organization for gateway calls in this run.
`--scope`	Default request scope; default `local`.
`--traces`, `--no-traces`	Enable or disable trace export.
`--sync-sessions`, `--no-sync-sessions`	Enable or disable transcript sync.
`--no-watch`	Disable hot reload.
`--oauth-cloud`	Use the selected cloud agent's OAuth bindings, shared with its deployments; default off.
`--open`	Open the chat UI in a browser; default off.
`-V`, `--verbose`	Increase log verbosity.
`-q`, `--quiet`	Show errors only.

Run Evals

amodal eval                         # every eval in evals/
amodal eval refund                  # IDs containing "refund"
amodal eval journeys/               # directory prefix, at any depth
amodal eval '/^l[23]\//'             # regular expression
amodal eval --tag safety             # manifest tag; repeat for OR matching
amodal eval --json                   # JSON results
amodal eval --record-dir out/        # training records as JSONL
amodal eval --path ./agent           # another agent directory
amodal eval --url http://localhost:3847

Without --url, the CLI starts a local runtime on an ephemeral port and stops it when the run finishes. It uses the same model routing as amodal dev.

--url targets an existing server's eval endpoints. The command does not send runtime bearer tokens or browser cookies, so it cannot authenticate to a gated hosted runtime. Use Amodal's Evals page or the Platform API for hosted evals.

The command exits nonzero if any eval fails or no evals run. The suite timeout defaults to five minutes; --timeout takes milliseconds. A timed-out suite preserves completed results and reports how many evals finished. Per-eval timeoutMs limits still apply.

See Evals for file formats and assertions.

Manage Connections

Declare, configure, and authorize the agent's named connections. Each command addresses a connection by its directory name under connections/. add and remove write the working tree at --path; they do not commit or push to GitHub. They use amodal/connections/ when it contains entries, otherwise connections/. The other actions manage OAuth bindings and accounts on the agent selected at login, and --agent overrides that agent. list lists those bindings and accounts, not every connection declared in the repository.

amodal connections add crm --rest https://api.example.com          # spec.json with a bearer token from CRM_API_KEY, policy.json
amodal connections add linear --mcp https://mcp.linear.app/mcp     # spec.json for an OAuth MCP server
amodal connections add analytics --provider google-analytics --rest https://analyticsdata.googleapis.com/v1beta
amodal connections remove crm --local            # delete the directory and the local binding
amodal connections list                          # bindings and authorized accounts
amodal connections configure analytics --config oauth.json --secret-stdin
amodal connections connect analytics             # browser consent; polls until it completes
amodal connections status analytics --json
amodal connections test analytics --path ./agent # run the connection's declared safe test
amodal connections disconnect analytics          # disable the account, revoke when supported

remove --local deletes the local binding without disconnecting its account. Removing files without --local leaves cloud bindings and accounts unchanged. disconnect disables an account for every binding that shares it and attempts provider revocation; it retains the bindings.

connect prints the authorization link and opens it in a browser; --no-open prints it only. --local keeps credentials on this machine under ~/.amodal/oauth/ instead of the platform, and the callback URL becomes http://127.0.0.1:8788/callback.

Connection Options

Option	Description
`<action>`	`add`, `remove`, `list`, `configure`, `connect`, `status`, `test`, or `disconnect`.
`[name]`	Connection name; required for every action except `list`.
`--rest`, `--mcp`, `--provider`	`add`: the REST base URL, the HTTP MCP server URL, or the managed OAuth provider ID (`--rest` may accompany `--provider`).
`--auth`	`add`: `bearer`, `api_key`, `basic`, `header`, or `oauth2`; default `bearer` for `--rest`, `oauth2` for `--mcp` and `--provider`.
`--header`	`add`: header name for `--auth header`.
`--secret-name`	`add`: environment variable holding the token; default `<NAME>_API_KEY`, `<NAME>_BASIC_AUTH` for `basic`, `<NAME>_TOKEN` for an MCP server. Names are uppercased, punctuation becomes `_`, and a leading digit gets an `_` prefix.
`--oauth`	`add`: `oauth.json` to copy for a custom OAuth application.
`--agent`	Cloud agent ID; defaults to the agent selected at login.
`--local`	Use the private local store instead of the platform; not with `--managed`. `remove --local` also deletes the local binding.
`--path`	Agent directory written by `add` and `remove` and read by `--local` and `test`; default `.`.
`--config`	JSON application configuration without secrets; required by `configure` unless selecting `--grant` or `--managed`. The CLI does not read the connection's `oauth.json` automatically.
`--grant`	Bind an existing authorized account by ID.
`--managed`	Bind a managed application by ID.
`--secret-stdin`	Read the client secret from standard input.
`--callback-port`	Loopback callback port for `--local` `connect`; default `8788`.
`--no-open`	Print the authorization link without opening a browser.
`--json`	Single-line JSON output; the default is indented.

Index Reference Corpora

amodal corpus index --path ./agent --app "$AMODAL_AGENT_ID"

This embeds type: corpus knowledge and stores its search index. --app must match the agent ID used by the searching runtime; it defaults to local. Configure CORPUS_EMBEDDING_URL, CORPUS_EMBEDDING_API_KEY, and the chosen vector store first. The PostgreSQL store uses CORPUS_DATABASE_URL or DATABASE_URL.

Unchanged content reuses cached embeddings. --json prints results as JSON. Failed or skipped corpora cause a nonzero exit. See Knowledge Base.

Manage Deployments

Deployment commands build the active agent's connected source. Commit and publish Git changes before deploying; these commands do not upload the local working directory.

amodal deploy-settings
amodal deploy --wait
amodal deploy --branch feature-x --env preview --wait
amodal deploy-status "$DEPLOY_ID" --watch
amodal promote --from-env preview --to-env production
amodal rollback --env production --deploy-id "$KNOWN_GOOD_DEPLOY_ID"

Use --agent <id> to override the selected agent for deploy, promote, rollback, or settings commands. Waiting for a deployment defaults to ten minutes; --timeout takes milliseconds. A finished deployment may still need activation, depending on the deploy settings.

Promotion copies the active deployment from the source environment into the destination environment. Rollback with --deploy-id selects that specific deployment. Without it, rollback selects the second-most-recent deployment in the environment, which is not necessarily the last one you tested.

Promotion, rollback, and deploying a non-production branch into production require confirmation. Pass --yes in noninteractive scripts.

amodal deploy-settings --production-branch main
amodal deploy-settings --auto-deploy --no-auto-promote-production

See Deployment API for the distinction between building, activating, and promoting.

Upgrade

amodal upgrade                     # latest published version
amodal upgrade --to "$CLI_VERSION"       # a specific published version
amodal upgrade --force              # reinstall the selected version