CLI overview

Global

amics [global options] <command>

Global options may appear before the command or among its options. They are never parsed after the literal -- separator used by amics run and amics serve.

Updates and agent skill

amics update
amics skill install [--agent AGENT] [--copy] [--yes]

update downloads, verifies, and atomically installs the current stable CLI. skill install asks which agents should receive the bundled skill. Repeat --agent to choose targets explicitly, select --agent universal for ~/.agents/skills/amics, or use --copy where symlinks are unavailable.

login

amics login [--no-browser]

Authentication and setup

amics auth status [--json]
amics auth logout [--local-only] [--yes]
amics doctor [--json]

auth logout revokes the active CLI key, then removes its matching saved copy. --local-only skips revocation for offline recovery. doctor checks the CLI build, credential, control plane, agent skill, and PATH.

Shell completion

amics completion bash
amics completion fish
amics completion zsh

Redirect the output to the completion directory used by your shell.

gpu options

amics gpu options [GPU OPTIONS] [--max-runtime DURATION]

This read-only command prints a table of live options. Pass --json for a JSON array. Each option describes one exact family, location, price, capacity depth, and quote expiry. The command does not rank unlike GPU families or select one for execution. Remove spaces from a displayed family before passing it to amics run --gpu (RTX 4090 becomes RTX4090).

run

amics run [OPTIONS] -- COMMAND [ARG...]

Run durations must be at least 60 seconds and may be at most 24 hours. The default is one hour. --keep-warm may be at most 24 hours and cannot be used with --compute. Use amics run --help for the authoritative option list and validation rules for the installed version.

Default human-readable output includes lifecycle stages before command output. Quiet, JSON, and JSONL modes keep their existing output contracts.

--storage GB selects 1–10,000 GB of attached disk for run, serve, and gpu options (default: 50 GB). Quotes include the requested storage.

GPU options

amics gpu options prints supported market prices and marks options with live capacity. Add --available to show only GPUs currently eligible to launch from marketplace availability or cloud quota signals, or --json for structured output.

Durations accept s, m, h, or d.

serve and services

amics serve [GPU OPTIONS] --max-hourly-price USD --ttl DURATION \
  [--port PORT] [--health-path PATH] [--env NAME] [--yes] -- COMMAND [ARG...]
amics services open SERVICE_ID
amics services get SERVICE_ID
amics services stop SERVICE_ID

serve snapshots the current project and starts one HTTP process as a bounded run. --ttl is required, --port defaults to 8000, and --health-path defaults to /health. The printed URL becomes usable when services get reports service.status as ready. Authenticate requests to that URL with the same Amics API key; Amics removes it before forwarding to the application.

For browser applications, run amics services open SERVICE_ID and open the printed localhost URL. Keep the command running for HTTP and WebSocket access. Your API key stays in the CLI; Ctrl-C closes browser access without stopping the service or its billing.

For an OpenAI-compatible server, append /v1 to the printed URL:

BASE_URL=$(amics serve --gpu L40S --max-hourly-price 1.50 --ttl 8h --yes -- \
  uv run vllm serve Qwen/Qwen3-8B --port 8000)
curl -H "Authorization: Bearer $AMICS_API_KEY" "$BASE_URL/v1/models"

The service and its compute stop at the TTL even if the client disconnects. services stop releases them earlier.

Runs and compute

amics runs list
amics runs get RUN_ID
amics runs logs RUN_ID [--cursor CURSOR] [--follow] [--jsonl]
amics runs cancel RUN_ID [--generation NUMBER] [--stop-compute]
amics services open SERVICE_ID
amics services get SERVICE_ID
amics services stop SERVICE_ID
amics compute list [--json]
amics compute stop COMPUTE_ID

runs list recovers recent run IDs and compute list recovers reusable lease IDs, so detached work never depends on terminal scrollback.

runs logs without --follow returns one bounded page. Use --follow to read through the current end. To resume a paged read, add --jsonl, copy the opaque cursor from the last output frame, then pass it to the next invocation:

amics runs logs RUN_ID --jsonl
amics runs logs RUN_ID --cursor OPAQUE_CURSOR --jsonl

JSONL preserves its command-output frame schema.

compute upload

amics compute upload COMPUTE_ID LOCAL_FILE --to /absolute/destination/path [--overwrite] [--json]

Uploads one local regular file to a running compute lease while its current command continues. COMPUTE_ID is a lease ID from amics compute list, and LOCAL_FILE is read as a regular file from the local machine. The destination must be an absolute path to a file in the active source or workspace tree; its parent directory must already exist. Path traversal, symlink escapes, and platform-specific path forms are rejected.

Uploads use 4 MiB chunks with per-chunk and whole-file SHA-256 verification. The destination is finalized only after the complete file has arrived. An existing destination is preserved unless --overwrite is supplied. The compute must still have the same running command and generation when each chunk is sent; stopping or replacing the run rejects the upload.

Use --json for a machine-readable completion object. A key used by the command needs compute manage permission. The control plane and runtime must be updated before the compute lease or run starts; an older running lease cannot be upgraded in place to add the upload gateway. Pressing Ctrl-C stops the current transfer and returns status 130; it leaves the running compute and its command alone.

Exit statuses

A remote process can itself return 64, 70, 75, or 130. When a run ID exists, inspect amics runs get RUN_ID and use its status, exit_code, termination_signal, and failure fields before interpreting an overlapping status. Never replay an unknown run automatically.