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.

Running the installer again deletes and recreates ~/.amodal, which also removes the stored login session and locally stored OAuth credentials. Use amodal upgrade to update an existing installation.

Commands

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.

To sign in without a browser, pass a platform token of kind cli:

amodal login --token "$AMODAL_CLI_TOKEN"

The Automation Tokens page does not offer the cli kind. Create one with POST /api/orgs/{org_id}/automation-tokens and "kind": "cli". The observer, operator, and admin kinds cannot reach the CLI's organization, agent, gateway, and telemetry endpoints. 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.

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. 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:

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

amodal dev runs every request under the scope local. Choose another scope with:

amodal dev ./agent --scope mission-42

A scope_id in the request body does not override this scope. Agents configured to require a scope therefore run locally without one in the request; see amodal.json.

Traces And Session Sync

Trace export and session sync send local runs to the selected agent's Traces and Sessions pages, using your login session. Both are on by default for gateway runs and off for runs using your own provider key. Toggle them with --traces/--no-traces and --sync-sessions/--no-sync-sessions. The Traces: exporting to ... startup line confirms export is active.

Both 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. Session sync is best effort, and the in-memory store remains the runtime's working store.

Startup Checks

Startup reports the model, routing, scope, and runtime URL. It lists missing provider keys, env: references in root-level connections/*/spec.json, variables in root-level tools/*/tool.json env arrays, and uninstalled packages declared in package.json dependencies or as plain strings in the amodal.json packages array. The scan does not read amodal/connections/ or amodal/tools/, so check those definitions yourself when a connection or tool reports a missing variable.

Dev Options

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
amodal eval --trace-file spans.jsonl # every span as JSONL, for a local run

Without --url, the CLI starts a local runtime on an ephemeral port and stops it when the run finishes. It accepts the same model-routing flags as amodal dev: --model, --provider, --base-url, --gateway, --org, --traces, and --port. Evals do not sync their sessions.

--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

Each command addresses a connection by its directory name. add and remove write the working tree at --path and do not commit. They use amodal/connections/ when it contains entries, otherwise connections/. The other actions manage OAuth bindings and accounts on the agent selected at login, or in the local store with --local. list lists those bindings and accounts, not every connection declared in the repository. See OAuth connections for examples and the authorization workflow.

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 --wait                                   # production branch into production
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"
amodal deploy-settings                                 # print the settings
amodal deploy-settings --production-branch main --auto-deploy --no-auto-promote-production
amodal deploy-settings --root-dir agent                # folder holding amodal.json; "" for the repo root

amodal deploy defaults to the production branch from deploy settings and the production environment. Any other environment must be passed explicitly with --env. --message attaches a deploy message. --agent <id> overrides the selected agent for deploy, promote, rollback, and deploy-settings. --wait and --watch stop after ten minutes by default; --timeout takes milliseconds.

Promotion, rollback, and deploying a branch other than the production branch into production ask for confirmation. Pass --yes in noninteractive scripts. See Deployment API for how building, activating, promoting, and rolling back differ.

Upgrade

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