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, delete, connect):

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

When neither flag is set, the default behavior depends on login state: if you are logged in, both local and remote sandboxes are shown; otherwise only local. --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 claude preset image
amika sandbox create --name claude-box --preset claude

# 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

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 `claude` (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`

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.

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

amika sandbox list

Output columns: NAME, LOCATION, PROVIDER, IMAGE, 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

amika sandbox delete 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
`--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.

`amika volume`

Manage tracked Docker volumes used by sandboxes.

amika volume list
amika volume delete my-volume
amika volume delete my-volume --force

Volume list output columns: NAME, TYPE, CREATED, IN_USE, SANDBOXES, SOURCE.

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

`amika service`

Manage services declared in sandbox configurations.

List

amika service list
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

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 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 claude --cmd "claude --help" --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 `claude` (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_RUN_EXPENSIVE_TESTS`	Enable expensive integration tests

CLI and API

System reference

CLI reference

`amika sandbox`

Global sandbox flags

Create

Create flags

Mount modes

List

Connect

Delete

`amika volume`

`amika service`

List

`amika auth`

`amika auth status`

`amika auth logout`

`amika auth extract`

`amika materialize`

Flags

Environment variables

CLI and API

System reference

​amika sandbox

​Global sandbox flags

​Create

​Create flags

​Mount modes

​List

​Connect

​Delete

​amika volume

​amika service

​List

​amika auth

​amika auth login

​amika auth status

​amika auth logout

​amika auth extract

​amika materialize

​Flags

​Environment variables

`amika sandbox`

Global sandbox flags

Create

Create flags

Mount modes

List

Connect

Delete

`amika volume`

`amika service`

List

`amika auth`

`amika auth login`

`amika auth status`

`amika auth logout`

`amika auth extract`

`amika materialize`

Flags

Environment variables