CLI reference

Use this page as the command index for the amika CLI.

`amika rig`

Manage hosted rigs.

amika sandbox remains available as a compatibility alias. Use amika rig in new commands and scripts.

Global rig flags

Rigs are always hosted. --remote remains an accepted no-op for compatibility. The retired --local flag is hidden and returns an error.

Create

# Use the current Git repository and generate a rig name
amika rig create

# Use the repository containing a specific path
amika rig create --name dev-rig --git ./src

# Use a remote Git repository
amika rig create --name dev-rig \
  --git https://github.com/gofixpoint/example-repo.git

# Use the preset that includes Docker
amika rig create --name dind-box --preset coder-plus-docker

# Set environment variables
amika rig create --name dev-rig --env MY_KEY=my_value

# Create and immediately connect
amika rig create --name dev-rig --connect

# Override the setup script
amika rig create --name dev-rig --setup-script ./install-deps.sh

# Clone a specific git branch
amika rig create --name dev-rig --branch develop

# Create a new branch from your current branch
amika rig create --new-branch feature-x

# Create a new branch starting from a specific existing branch
amika rig create --branch main --new-branch bugfix-1

# Inject a stored secret
amika rig create --name dev-rig \
  --secret env:ANTHROPIC_API_KEY=my-claude-key

# Pin which agent credential gets injected at create time
amika rig create --name dev-rig \
  --agent-credential-type claude=api-key \
  --no-agent-credential codex

# Create a rig without a repository
amika rig create --name scratch --no-git

Create flags

Flag	Default	Description
`--name <name>`	auto-generated	Name for the rig. If omitted, a random `{color}-{city}` name is generated
`--preset <name>`	repository or platform default	Use `coder` or `coder-plus-docker`
`--size <size>`	repository or platform default	Rig size, such as `m` or `a1.medium`
`--snapshot <slug>`		Fork from a captured snapshot
`--git <path-or-URL>`	auto-detected	Use a local repository path or a Git URL. If omitted, the CLI detects a repository from the current directory
`--no-git`	`false`	Skip git repo auto-detection; create a repo-less rig with no repo mounted
`--env <KEY=VALUE>`		Set environment variable. Repeatable
`--secret <spec>`		Inject a stored secret (`env:FOO=SECRET_NAME` or `env:SECRET_NAME`). Repeatable
`--connect`	`false`	Connect to the rig shell immediately after creation
`--setup-script <path>`		Upload a local setup script
`--no-setup`	`false`	Replace the configured setup script with a no-op script
`--branch <name>`		Check out this branch, or create it if the remote has none
`--new-branch <name>`		Create a new branch from `--branch` or the inferred base branch
`--github-auth-mode <mode>`	platform default	GitHub authentication mode: `pat`, `app_token`, or `app-token`
`--agent-credential <KIND=NAME>`		Pin an agent credential by stored name (e.g. `claude=personal-oauth`). Repeatable per kind
`--agent-credential-type <KIND=TYPE>`		Pin an agent credential by type, where `TYPE` is `oauth` or `api-key` (e.g. `claude=oauth`). Repeatable per kind
`--no-agent-credential <KIND>`		Skip injecting any credential of this kind (e.g. `codex`). Repeatable per kind

--no-setup and --setup-script are mutually exclusive.

Supported agent kinds for --agent-credential, --agent-credential-type, and --no-agent-credential are claude and codex. Each flag may appear at most once per kind. --no-agent-credential is mutually exclusive with the other two for the same kind. See Inject credentials for usage.

Hosted rigs clone from the repository remote. Push local commits before creation. The CLI rejects an inferred branch that is not present and up to date on origin.

List

Aliases: ls

amika rig list
amika rig ls

Output columns: NAME, STATE, LOCATION, PROVIDER, IMAGE, BRANCH, PORTS, CREATED.

Connect

# Connect with default shell (zsh)
amika rig connect dev-rig

# Connect with a different shell
amika rig connect dev-rig --shell bash

Flag	Default	Description
`--shell <shell>`	`zsh`	Shell to run in the rig container

The shell starts in /home/amika.

Delete

Aliases: rm, remove

amika rig delete dev-rig
amika rig rm dev-rig
amika rig delete rig-1 rig-2
amika rig delete dev-rig --delete-volumes
amika rig delete dev-rig --keep-volumes

Flag	Default	Description
`--force`	`false`	Skip confirmation prompt
`--delete-volumes`	`false`	Delete associated volumes that are no longer referenced by other rigs
`--keep-volumes`	`false`	Keep associated volumes without prompting

When neither flag is set and the rig is the sole reference for a volume, you will be prompted to decide.

Stop

Stop one or more running rigs without removing them.

amika rig stop dev-rig
amika rig stop rig-1 rig-2

Start

Start (resume) one or more stopped rigs.

amika rig start dev-rig
amika rig start rig-1 rig-2

SSH

SSH into a remote rig, or revoke SSH access. Optionally pass a command to execute instead of opening an interactive session.

# Interactive SSH session
amika rig ssh my-rig

# Run a command on the remote rig
amika rig ssh my-rig -- ls -la

# Force pseudo-terminal allocation (for interactive programs)
amika rig ssh -t my-rig -- top

# Revoke SSH access
amika rig ssh my-rig --revoke

Flag	Default	Description
`-t`	`false`	Force pseudo-terminal allocation (useful for interactive remote programs)
`--revoke`	`false`	Revoke SSH access for the rig

Code

Open a remote rig in an editor via SSH.

amika rig code my-rig
amika rig code my-rig --editor=cursor

Flag	Default	Description
`--editor <name>`	`cursor`	Editor to open (currently only `cursor` is supported)

Agent Send

Send a prompt to an AI agent CLI running inside a rig container. The message can be provided as a positional argument or piped via stdin. By default the command waits for the agent to finish and streams the response.

# Send a message to Claude in a rig
amika rig agent-send my-rig "Add unit tests for the auth module"

# Pipe a message via stdin
echo "Fix the failing tests" | amika rig agent-send my-rig

# Send without waiting for a response
amika rig agent-send my-rig "Refactor the API layer" --no-wait

# Use a different agent CLI
amika rig agent-send my-rig "Review this code" --agent codex

Flag	Default	Description
`--no-wait`	`false`	Send the instruction and return immediately without waiting
`--workdir <path>`	`$AMIKA_AGENT_CWD`	Working directory inside the container
`--agent <name>`	`claude`	Agent CLI to use
`--session-id <id>`		Resume an existing agent session. Remote rigs only
`--new-session`	`false`	Start a new agent session instead of resuming. Remote rigs only

`amika snapshot`

Manage snapshots captured from running rigs. Snapshots are a hosted-cloud concept — every subcommand talks to the API — so they are not available in local open-source mode. See Create a snapshot for the end-to-end flow.

Create

Capture a snapshot from a running rig. Interactive by default: it prompts for the capture mode and name, and for scrub_and_delete it previews the injected secrets that will be removed and asks for confirmation. Pass --no-interactive for a non-prompting run, which then requires --mode and --name.

# Interactive
amika snapshot create --sandbox base-box

# Non-interactive
amika snapshot create --sandbox base-box \
  --name example-repo-base --mode scrub_and_delete --no-interactive

Flag	Default	Description
`--sandbox <name-or-id>`	(required)	Source rig to snapshot
`--name <name>`		Name for the snapshot (prompted if omitted in interactive mode)
`--mode <mode>`		Capture mode: `scrub_and_delete` or `full` (required with `--no-interactive`)
`--description <text>`		Optional description shown in the snapshot list
`--no-interactive`	`false`	Do not prompt; requires `--mode` and `--name`

Capture modes:

Mode	Behavior
`scrub_and_delete` (default)	Remove Amika-injected secrets, capture the snapshot, then delete the source rig
`full`	Capture everything as-is (keeps secrets and the source rig; unsafe for shared images)

Capture runs in the background; check progress with amika snapshot list.

List

Aliases: ls

amika snapshot list
amika snapshot ls --long
amika snapshot list --sandbox base-box
amika snapshot list --repo example-repo

Output columns: NAME, STATE, PROVIDER, SOURCE, CREATED (plus SIZE, BASE, DESCRIPTION, and ERROR with --long).

Flag	Default	Description
`-l`, `--long`	`false`	Show additional columns
`--sandbox <name-or-id>`		Only show snapshots captured from this rig
`--repo <name-or-id>`		Only show snapshots for this repository

Delete

Aliases: rm, remove

amika snapshot delete example-repo-base
amika snapshot rm snap-1 snap-2
amika snapshot delete example-repo-base --force

Flag	Default	Description
`-f`, `--force`	`false`	Skip confirmation prompt

`amika volume`

Manage tracked Docker volumes used by rigs.

List

Aliases: ls

amika volume list
amika volume ls

Output columns: NAME, TYPE, CREATED, IN_USE, SANDBOXES, SOURCE.

Delete

Aliases: rm, remove

amika volume delete my-volume
amika volume rm my-volume
amika volume delete my-volume --force

Flag	Default	Description
`--force`	`false`	Delete volume even if still referenced by rigs

`amika service`

Manage services declared in rig configurations.

List

Aliases: ls

amika service list
amika service ls
amika service list --rig-name dev-rig

Output columns: SERVICE, SANDBOX, PORTS, URL.

Flag	Default	Description
`--rig-name <name>`	(none)	Filter services to a specific rig

See Services for how to declare services in .amika/config.toml.

`amika auth`

Authentication and credential commands. Log in to Amika via the WorkOS Device Authorization Flow. Opens a browser for you to authorize the CLI.

amika auth login

To skip the browser flow and log in with an Amika API key — useful in CI — pass --api-key-file. Use - to read from stdin so the key never lands on disk:

amika auth login --api-key-file /path/to/key
vault kv get -field=key secret/amika | amika auth login --api-key-file -

Flag	Default	Description
`--api-key-file <path \| ->`		Read an Amika API key from this path (or `-` for stdin) instead of running the device flow

See Authentication for details on the login flow and session storage.

`amika auth status`

Show current authentication status.

amika auth status

Prints the logged-in email and organization, or “Not logged in” if no session exists.

`amika auth logout`

Log out of Amika and remove the saved session.

amika auth logout

`amika auth extract`

Discover locally stored credentials from multiple sources and print shell environment assignments.

amika auth extract
eval "$(amika auth extract --export)"
amika auth extract --homedir /tmp/test-home
amika auth extract --no-oauth

Flag	Default	Description
`--export`	`false`	Prefix each line with `export`
`--homedir <path>`	`$HOME`	Override home directory used for credential discovery
`--no-oauth`	`false`	Skip OAuth credential sources

See Authentication for details on supported credential sources and priority.

`amika secret`

Manage secrets in the remote Amika secrets store.

`amika secret extract`

Discover locally stored credentials and optionally push them to the remote store.

amika secret extract
amika secret extract --push
amika secret extract --push --only=ANTHROPIC_API_KEY,OPENAI_API_KEY

Flag	Default	Description
`--push`	`false`	Push discovered secrets to the remote store after confirmation
`--only <keys>`		Comma-separated list of secret names to include (e.g. `ANTHROPIC_API_KEY,OPENAI_API_KEY`)
`--scope <scope>`	`user`	Secret scope: `user` (private) or `org` (visible to org members)
`--homedir <path>`		Override home directory used for credential discovery
`--no-oauth`	`false`	Skip OAuth credential sources

`amika secret push`

Push secrets to the remote store from inline arguments, environment variables, or a .env file.

amika secret push ANTHROPIC_API_KEY=sk-ant-xxx
amika secret push --from-env=ANTHROPIC_API_KEY,OPENAI_API_KEY
amika secret push --from-file=.env
amika secret push --from-file=.env CUSTOM_KEY=val --from-env=ANTHROPIC_API_KEY

Flag	Default	Description
`--from-env <keys>`		Comma-separated list of environment variable names to read and push
`--from-file <path>`		Path to a `.env` file containing `KEY=VALUE` secrets
`--scope <scope>`	`user`	Secret scope: `user` (private) or `org` (visible to org members)

When multiple sources are used, positional arguments override --from-file values, and --from-env overrides both.

`amika secret claude`

Manage Claude Code credentials for rig authentication. Credentials pushed here can be injected into rigs at creation time.

`amika secret claude push`

Push Claude Code credentials (API key or OAuth token) to the remote Amika secrets store. Scans your system for Claude credentials and lets you choose which one to push. On macOS, the keychain is also checked.

# Interactive — discover and select credentials
amika secret claude push

# Push with a custom label
amika secret claude push --name "Claude OAuth (Work Laptop)"

# Push from a credentials file
amika secret claude push --from-file ~/.claude/.credentials.json

# Push a credential value directly
amika secret claude push --value '{"claudeAiOauth":{...}}'

# Auto-resolve by type (reads ANTHROPIC_API_KEY env var for api_key)
amika secret claude push --type api_key

Flag	Default	Description
`--name <label>`		Human-readable label for the credential (prompted if omitted)
`--value <string>`		Credential value (skips interactive discovery)
`--from-file <path>`		Path to a credentials file (skips interactive discovery)
`--type <type>`	`oauth`	Credential type: `oauth` or `api_key`

--value and --from-file are mutually exclusive.

`amika secret claude list`

Aliases: ls List pushed Claude credentials.

amika secret claude list
amika secret claude ls

Output columns: ID, NAME, TYPE.

`amika secret claude delete`

Aliases: rm Delete a Claude credential by ID.

amika secret claude delete <id>
amika secret claude rm <id>

`amika secret codex`

Manage Codex credentials for rig authentication. Same shape as amika secret claude — pushed credentials can be injected into rigs at creation time.

`amika secret codex push`

Push Codex credentials (API key or OAuth token) to the remote Amika secrets store. Scans ~/.codex/auth.json for credentials and lets you choose which one to push.

# Interactive — discover and select credentials
amika secret codex push

# Push with a custom label
amika secret codex push --type oauth --name "Codex OAuth"

# Push from ~/.codex/auth.json
amika secret codex push --from-file ~/.codex/auth.json

# Push a credential value directly
amika secret codex push --value '{"tokens":{"access_token":"..."}}'

# Auto-resolve by type
amika secret codex push --type api_key  # reads OPENAI_API_KEY env, falls back to ~/.codex/auth.json
amika secret codex push --type oauth    # reads ~/.codex/auth.json

Flag	Default	Description
`--name <label>`		Human-readable label for the credential (prompted if omitted)
`--value <string>`		Credential value (skips interactive discovery)
`--from-file <path>`		Path to a credentials file (skips interactive discovery)
`--type <type>`	`oauth`	Credential type: `oauth` or `api_key`

--value and --from-file are mutually exclusive.

`amika secret codex list`

Aliases: ls List pushed Codex credentials.

amika secret codex list
amika secret codex ls

Output columns: ID, NAME, TYPE.

`amika secret codex delete`

Aliases: rm Delete a Codex credential by ID.

amika secret codex delete <id>
amika secret codex rm <id>

`amika materialize`

Run a script or command in an ephemeral Docker container and copy output files to a destination. The container runs with working directory /home/amika/workspace. Exactly one of --script or --cmd must be specified.

amika materialize --script ./pull-data.sh --destdir ./output
amika materialize --cmd "curl -s https://api.example.com/data > result.json" --destdir ./output
amika materialize --script ./transform.sh --outdir /app/results --destdir ./output
amika materialize -i --cmd claude --mount $(pwd):/workspace --env ANTHROPIC_API_KEY=...
amika materialize --preset coder-plus-docker --cmd "docker ps" --destdir /tmp/out
amika materialize --setup-script ./install-deps.sh --cmd "echo done" --destdir /tmp/out

Flags

Flag	Default	Description
`--script <path>`		Script to execute (mutually exclusive with `--cmd`)
`--cmd <string>`		Bash command to execute (mutually exclusive with `--script`)
`--destdir <path>`	(required)	Host directory where output files are copied
`--outdir <path>`	workdir	Container directory to copy from
`--image <image>`	`amika/coder:latest`	Docker image to use (mutually exclusive with `--preset`)
`--preset <name>`		Preset image, e.g. `coder` or `coder-plus-docker` (mutually exclusive with `--image`)
`--mount <spec>`		Mount a host directory (`source:target[:mode]`, mode defaults to `rw`). Repeatable
`--env <KEY=VALUE>`		Set environment variable in the container. Repeatable
`-i`, `--interactive`	`false`	Run interactively with TTY
`--setup-script <path>`		Mount startup script at `/usr/local/etc/amikad/setup/setup.sh`

Pass script args after --:

amika materialize --script ./gen.sh --destdir /tmp/dest -- arg1 arg2

Environment variables

Variable	Description
`AMIKA_STATE_DIRECTORY`	Override the default state directory (`~/.local/state/amika`)
`AMIKA_PRESET_IMAGE_PREFIX`	Override the Docker image name prefix for presets
`AMIKA_API_URL`	Override the remote API base URL (default: `https://app.amika.dev`). Used by rig commands when operating on remote rigs
`AMIKA_WORKOS_CLIENT_ID`	Override the default WorkOS client ID for `amika auth login`. If you change `AMIKA_API_URL`, you likely need to update this too
`AMIKA_API_KEY`	Static bearer token for API authentication. When set, takes precedence over the WorkOS session from `amika auth login`
`AMIKA_RUN_EXPENSIVE_TESTS`	Enable expensive integration tests

​amika rig

​Global rig flags

​Create

​Create flags

​List

​Connect

​Delete

​Stop

​Start

​SSH

​Code

​Agent Send

​amika snapshot

​Create

​List

​Delete

​amika volume

​List

​Delete

​amika service

​List

​amika auth

​amika auth login

​amika auth status

​amika auth logout

​amika auth extract

​amika secret

​amika secret extract

​amika secret push

​amika secret claude

​amika secret claude push

​amika secret claude list

​amika secret claude delete

​amika secret codex

​amika secret codex push

​amika secret codex list

​amika secret codex delete

​amika materialize

​Flags

​Environment variables

`amika rig`

Global rig flags

Create

Create flags

List

Connect

Delete

Stop

Start

SSH

Code

Agent Send

`amika snapshot`

Create

List

Delete

`amika volume`

List

Delete

`amika service`

List

`amika auth`

`amika auth login`

`amika auth status`

`amika auth logout`

`amika auth extract`

`amika secret`

`amika secret extract`

`amika secret push`

`amika secret claude`

`amika secret claude push`

`amika secret claude list`

`amika secret claude delete`

`amika secret codex`

`amika secret codex push`

`amika secret codex list`

`amika secret codex delete`

`amika materialize`

Flags

Environment variables