> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amika.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Commands, flags, and examples for the Amika CLI.

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

```bash theme={null}
# 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                                                      |

<Note>
  The `--secret` flag requires `--remote` mode — secrets are resolved by the remote API.
</Note>

<Note>
  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](/guides/inject-credentials) for usage.
</Note>

<Note>
  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](/reference/services) for details.
</Note>

<Note>
  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.
</Note>

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

```bash theme={null}
amika sandbox list
amika sandbox ls
```

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

### Connect

```bash theme={null}
# 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`

```bash theme={null}
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.

```bash theme={null}
amika sandbox stop dev-sandbox
amika sandbox stop sandbox-1 sandbox-2
```

### Start

Start (resume) one or more stopped sandboxes.

```bash theme={null}
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.

```bash theme={null}
# 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.

```bash theme={null}
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.

```bash theme={null}
# 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`

```bash theme={null}
amika volume list
amika volume ls
```

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

### Delete

Aliases: `rm`, `remove`

```bash theme={null}
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`

```bash theme={null}
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](/reference/services) for how to declare services in `.amika/config.toml`.

## `amika auth`

Authentication and credential commands.

### `amika auth login`

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

```bash theme={null}
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:

```bash theme={null}
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](/reference/auth) for details on the login flow and session storage.

### `amika auth status`

Show current authentication status.

```bash theme={null}
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.

```bash theme={null}
amika auth logout
```

### `amika auth extract`

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

```bash theme={null}
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](/reference/auth) 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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
# 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`                         |

<Note>
  `--value` and `--from-file` are mutually exclusive.
</Note>

#### `amika secret claude list`

Aliases: `ls`

List pushed Claude credentials.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
# 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`                         |

<Note>
  `--value` and `--from-file` are mutually exclusive.
</Note>

#### `amika secret codex list`

Aliases: `ls`

List pushed Codex credentials.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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 `--`:

```bash theme={null}
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                                                                                               |