CLI reference

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

`amika sandbox`

Manage Docker-backed persistent sandboxes with bind mounts and named volumes.

Global sandbox flags

These flags apply to all sandbox subcommands (create, list, connect, stop, start, delete, ssh, code, agent-send):

Flag	Default	Description
`--local`	`false`	Only operate on local sandboxes
`--remote`	`false`	Only operate on remote sandboxes

When neither flag is set, commands default to remote mode. Use --local to operate on local sandboxes only. --local and --remote are mutually exclusive.

Create

# Minimal — auto-generates a name, uses the coder preset image
amika sandbox create --yes

# Named sandbox with mounts
amika sandbox create --name dev-sandbox \
  --mount ./src:/workspace/src:ro \
  --mount ./out:/workspace/out

# Mount the current git repo (clean clone by default)
amika sandbox create --name dev-sandbox --git

# Mount git repo with untracked/uncommitted files included
amika sandbox create --name dev-sandbox --git --no-clean

# Mount git repo containing a specific path
amika sandbox create --name dev-sandbox --git ./src

# Use the coder-dind preset image
amika sandbox create --name dind-box --preset coder-dind

# Use a custom Docker image
amika sandbox create --name custom-box --image myimage:latest

# Attach an existing tracked volume
amika sandbox create --name dev-sandbox-2 \
  --volume amika-rwcopy-dev-sandbox-workspace-out-123:/workspace/out:rw

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

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

# Run a setup script on container start
amika sandbox create --name dev-sandbox --setup-script ./install-deps.sh

# Publish a container port to the host
amika sandbox create --name dev-sandbox --port 8080:8080

# Publish a port bound to all interfaces
amika sandbox create --name dev-sandbox --port 3000:3000 --port-host-ip 0.0.0.0

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

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

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

# Inject remote secrets (remote sandboxes only)
amika sandbox create --name dev-sandbox --git --remote \
  --secret env:ANTHROPIC_API_KEY=my-claude-key

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

Create flags

Flag	Default	Description
`--name <name>`	auto-generated	Name for the sandbox. If omitted, a random `{color}-{city}` name is generated
`--provider <name>`	`docker`	Sandbox provider (only `docker` is currently supported)
`--image <image>`	`amika/coder:latest`	Docker image to use (mutually exclusive with `--preset`)
`--preset <name>`		Use a preset environment, e.g. `coder` or `coder-dind` (mutually exclusive with `--image`)
`--mount <spec>`		Mount a host path (`source:target[:mode]`, mode defaults to `rwcopy`). Repeatable
`--volume <spec>`		Mount an existing named volume (`name:target[:mode]`, mode defaults to `rw`). Repeatable
`--git [path]`		Mount the git repo root (or repo containing `path`) to `/home/amika/workspace/{repo}`
`--no-clean`	`false`	With `--git`, include untracked/uncommitted files instead of a clean clone
`--env <KEY=VALUE>`		Set environment variable. Repeatable
`--port <spec>`		Publish a container port (`hostPort:containerPort[/protocol]`). Repeatable
`--port-host-ip <ip>`	`127.0.0.1`	Host IP address to bind published ports to. Use `0.0.0.0` for all interfaces
`--yes`	`false`	Skip mount confirmation prompt
`--connect`	`false`	Connect to the sandbox shell immediately after creation
`--setup-script <path>`		Mount a local script to `/usr/local/etc/amikad/setup/setup.sh`
`--branch <name>`		Check out this branch, or create it if it doesn’t exist. Used with `--git`
`--new-branch <name>`		Create a new branch (errors if it already exists). Starts from `--branch` if set, otherwise from the base branch. Used with `--git`
`--size <size>`	`m`	Sandbox resource size: `xs` or `m`. Remote sandboxes only
`--no-setup`	`false`	Skip the setup script (ignore both `--setup-script` and `.amika/config.toml` setup)
`--secret <spec>`		Inject a remote secret (`env:FOO=SECRET_NAME` or `env:SECRET_NAME`). Repeatable. Requires `--remote`
`--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

The --secret flag requires --remote mode — secrets are resolved by the remote API.

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.

When --git is used with a repo that contains .amika/config.toml service declarations, those service ports are published automatically. If a --port flag conflicts with a service port (same container port and protocol), the command returns an error. See Services for details.

The base branch is your current checked-out branch when --git is a local path, or the repo’s default branch when it’s a URL.

Mount modes

Mode	Behavior
`ro`	Read-only bind mount from host
`rw`	Read-write bind mount from host (writes sync back to host)
`rwcopy`	Read-write snapshot in a Docker volume (default for `--mount`). Host files are copied in; writes stay in the volume and do not sync back

List

Aliases: ls

amika sandbox list
amika sandbox ls

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

Connect

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

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

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

The shell starts in /home/amika.

Delete

Aliases: rm, remove

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

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

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

Stop

Stop one or more running sandboxes without removing them.

amika sandbox stop dev-sandbox
amika sandbox stop sandbox-1 sandbox-2

Start

Start (resume) one or more stopped sandboxes.

amika sandbox start dev-sandbox
amika sandbox start sandbox-1 sandbox-2

SSH

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

# Interactive SSH session
amika sandbox ssh my-sandbox

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

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

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

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

Code

Open a remote sandbox in an editor via SSH.

amika sandbox code my-sandbox
amika sandbox code my-sandbox --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 sandbox 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 sandbox
amika sandbox agent-send my-sandbox "Add unit tests for the auth module"

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

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

# Use a different agent CLI
amika sandbox agent-send my-sandbox "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 sandboxes only
`--new-session`	`false`	Start a new agent session instead of resuming. Remote sandboxes only

`amika volume`

Manage tracked Docker volumes used by sandboxes.

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 sandboxes

`amika service`

Manage services declared in sandbox configurations.

List

Aliases: ls

amika service list
amika service ls
amika service list --sandbox-name dev-sandbox

Output columns: SERVICE, SANDBOX, PORTS, URL.

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

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 sandbox authentication. Credentials pushed here can be injected into sandboxes 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 sandbox authentication. Same shape as amika secret claude — pushed credentials can be injected into sandboxes 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-dind --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-dind` (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 sandbox commands when operating on remote sandboxes
`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

CLI and platform

Repository configuration

HTTP API

CLI reference

`amika sandbox`

Global sandbox flags

Create

Create flags

Mount modes

List

Connect

Delete

Stop

Start

SSH

Code

Agent Send

`amika volume`

List

Delete

`amika service`

List

`amika auth`

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

​Global sandbox flags

​Create

​Create flags

​Mount modes

​List

​Connect

​Delete

​Stop

​Start

​SSH

​Code

​Agent Send

​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 sandbox`

Global sandbox flags

Create

Create flags

Mount modes

List

Connect

Delete

Stop

Start

SSH

Code

Agent Send

`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