Add amika-cli skill documenting the CLI for agents - #315
Conversation
Adds `.agents/skills/amika-cli/SKILL.md`, an agent-facing guide to driving the `amika` CLI non-interactively. `docs/cli-reference.md` already covers per-flag detail, but reads as a human reference: it does not explain that sandbox commands default to `--remote`, which commands reject `-o json`, or which confirmation flags an unattended run must pass to avoid blocking on a prompt. Agents get those wrong first. The skill leads with the local/remote model, the credential resolution order (`AMIKA_API_KEY` first, for headless runs), and four rules for non-interactive use, then covers sandbox creation, `agent-send`, `ssh`/`scp`, snapshots, services, and environment variables. Every claim was checked against `amika` v0.13.0, whose CLI sources match `main`.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9b6be25b99
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| schema. Batch mutations (`start`/`stop`/`delete` over several names) emit an | ||
| array of `{name, status, error?}` — a per-item failure shows up there, so check | ||
| it rather than trusting the exit code alone. |
There was a problem hiding this comment.
sandbox start and sandbox stop do not emit {name, status, error?} for successful targets: the reviewed implementation appends each target's final RemoteSandbox, while only failed targets use ItemResult. A consumer expecting .status on every successful entry will therefore receive null; document the mixed resource/error array separately from delete results.
AGENTS.md reference: AGENTS.md:L114-L114
Useful? React with 👍 / 👎.
|
|
||
| | Only remote | Only local | | ||
| | ----------- | ---------- | | ||
| | `sandbox ssh`, `sandbox code`, and `scp` sandbox operands | `sandbox create --no-clean` | |
There was a problem hiding this comment.
Because remote mode is the documented default, listing only --no-clean as local-only implies that host mounts, volumes, ports, custom images, and providers work remotely. In sandbox_create.go, the local path reads --image, --mount, --volume, --port, --port-host-ip, and --provider, but createRemoteSandbox never puts any of them in CreateSandboxRequest, so these accepted flags are silently ignored and the created sandbox lacks the requested resources.
Useful? React with 👍 / 👎.
| `amika scp` forwards every argument to the system `scp`, so `-r`, `-p`, `-C`, | ||
| `-v`, `-o Option=value` all work. Path forms: |
There was a problem hiding this comment.
For the common local-to-sandbox or sandbox-to-local case, runSCP uses planStreamTransfer instead of the system scp; splitOperandsAndFlags retains only -r and discards options such as -p, -C, -v, and user-supplied -o. Thus, for example, -p will not preserve modes or timestamps despite this promise, potentially leaving uploaded executables unusable; restrict this claim to transfers that actually take the scp path and document the streamed path's supported flags.
Useful? React with 👍 / 👎.
| ```bash | ||
| amika scp ./local.txt my-sandbox:local.txt | ||
| amika scp -r my-sandbox:/srv/out ./out | ||
| amika scp my-sandbox:/data.csv scp://user@host:22/tmp/data.csv |
There was a problem hiding this comment.
This example is exactly a sandbox-to-external transfer, which the following paragraph says is unsupported. planStreamTransfer excludes that shape and falls back to the system scp path; the implementation documents that this path can hang against the Daytona gateway after transferring the data. An agent following the example can therefore block indefinitely, contrary to this skill's non-interactive goal; show the required two-step local copy instead.
Useful? React with 👍 / 👎.
| | `AMIKA_API_URL` | Remote API base URL (default `https://app.amika.dev`) | | ||
| | `AMIKA_WORKOS_CLIENT_ID` | WorkOS client id for device login; change it alongside `AMIKA_API_URL` | | ||
| | `AMIKA_STATE_DIRECTORY` | State dir (default `$XDG_STATE_HOME/amika`, else `~/.local/state/amika`) — holds sandbox/volume/mount state, session, and API key | | ||
| | `AMIKA_SANDBOX_PROVIDER` | Override the sandbox provider | |
There was a problem hiding this comment.
Exporting AMIKA_SANDBOX_PROVIDER does not select or override a provider. A repo-wide search at the reviewed commit finds it only as an environment marker consumed by the sandbox preset's pre-setup.sh; the host CLI never reads it for provider selection, which instead uses --provider locally and server configuration remotely. Agents following this table will believe they changed providers while their commands continue using the previous/default provider.
Useful? React with 👍 / 👎.
Processes the `#amika/annotate` markers left on the skill. The skill now covers remote sandboxes only, which is what the CLI targets by default. Removes local-mode coverage, mounts and mount modes, the `amika volume` family, the WorkOS name (now "browser-authed session"), the `docs/cli-reference.md` pointer, and the instruction to run `amika version`. Dropping mounts exposed a wider gap: `createRemoteSandbox` returns before `--mount`, `--volume`, `--port`, `--port-host-ip`, `--image`, `--provider`, and `--yes` are read, so those are silently ignored on remote rather than merely unsupported. Remote `sandbox delete` likewise never prompts, making `--force` a no-op there. The create-flag list and the confirmation-flag table now reflect only what the remote path actually consumes. Adds a `.amika/config.toml` section covering per-repo sandbox defaults and the flags > UI > file > defaults resolution order, and notes that `secret push` always reads `[y/N]` from stdin with no bypass flag. Rule 4 now allows an interactive session when the caller can steer a TTY (a tmux session or pane), which is how to reach a REPL or TUI inside a sandbox. Tables are pipe-aligned to match the convention in amika-mono, where this file also lives byte-identical.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8cfc32a9e3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| `--mode` is `scrub_and_delete` (removes injected secrets) or `full`. Prefer | ||
| `scrub_and_delete` unless you have a reason to bake credentials into an image | ||
| others can fork. |
There was a problem hiding this comment.
When an agent follows the non-interactive example above, scrub_and_delete removes the injected secrets and then deletes the source sandbox; runSnapshotCreate makes this explicit in its confirmation text (snapshot the sandbox, and delete it?). Describing the mode only as removing secrets, and recommending it by default, can cause an unattended run to destroy a sandbox that the caller expected to keep, so document the deletion next to the example and mode description.
Useful? React with 👍 / 👎.
| | `sandbox delete` (`rm`) | Delete sandboxes; multiple names | | ||
| | `sandbox agent-send` | Send a prompt to a coding agent running inside a sandbox | | ||
| | `sandbox ssh` | SSH in, or run one command; `--print` emits the connection string; `--revoke` revokes access | | ||
| | `sandbox connect` | Interactive shell (`--shell`, default `zsh`), starting at `/home/amika` | |
There was a problem hiding this comment.
In the remote context assumed throughout this skill, sandbox connect --shell bash does not select bash: the remote branch of sandboxConnectCmd ignores the parsed shell value and calls ssh.ExecSSH with no command, so the server's default login shell opens instead. Although sandbox connect --help describes --shell as the “Shell to run in the sandbox container,” this behavior is only implemented by the local Docker branch; qualify the flag as local-only or omit it here.
Useful? React with 👍 / 👎.
| `--workdir` defaults to `$AMIKA_AGENT_CWD`, which `sandbox create` sets to the | ||
| checked-out repo path. |
There was a problem hiding this comment.
For the default synchronous remote agent-send path, runRemoteAgentSend accepts workdir but does not put it in apiclient.AgentSendRequest; only the --no-wait SSH path uses it to build the shell command. Thus an agent relying on the advertised “Working directory inside the container” flag to run a normal synchronous request in another directory will silently execute in the server-selected directory, potentially editing the wrong checkout; restrict this guidance to the paths that honor the flag.
Useful? React with 👍 / 👎.
1 participant
Adds
.agents/skills/amika-cli/SKILL.md, an agent-facing guide to driving theamikaCLI non-interactively. The same file is going intoamika-mono(branchdylan/amika-cli-skill) so both repos' agents share one description of the CLI —the two copies are byte-identical.
The skill covers remote sandboxes only, which is what the CLI targets by
default.
What it covers
Aimed at what agents get wrong on the first try, rather than restating per-flag
detail:
AMIKA_API_KEYcalled out as the headlesspath.
flag, don't request JSON from commands that can't emit it, and don't launch an
interactive session you can't steer (with a tmux exception for REPLs and
TUIs).
.amika/config.toml— per-repo sandbox defaults and theflags > UI > file > defaults resolution order.
sandbox create,agent-send,ssh/scp, snapshots, services, andenvironment variables.
Findings from writing it
Scoping the skill to remote surfaced a few things worth knowing independently of
the doc:
createRemoteSandboxreturns before--mount,--volume,--port,--port-host-ip,--image,--provider, and--yesare read. On remotethose flags are silently ignored, not merely unsupported — no error, no
warning.
sandbox deletenever prompts, so--forceis a no-op on that pathtoo. The confirmation-flag table is therefore just
snapshot create/snapshot delete/service delete.secret pushalways reads[y/N]from stdin with no bypass flag, soscripted use needs
echo y | amika secret push ….Verification
Behavioral claims were exercised against the installed
amikav0.13.0 binary,whose CLI sources are identical to
main— every rejection message, the[]-not-nullempty list, theunknown agenterror, and default-remoteresolution against an empty
AMIKA_STATE_DIRECTORY. Remote-path flag handlingwas read from
sandbox_create.goandsandbox_delete.gorather than tested,since exercising it would create and destroy real sandboxes.
Follow-up, not fixed here
docs/cli-reference.mdhas drifted. I left it alone rather than widen this PR:amika auth extractwith an--exportflag; that command is gone(it is now
amika secret extract, which has no--export).amika service,amika snapshot, orsecret codex.auth login --api-key-file,AMIKA_API_KEY,secret --scope/--force,sandbox create --size/--github-auth-mode/--agent-credential*,sandbox ssh --print,agent-send --session-id/--new-session.--presetis documented ascoderorclaude; the binary acceptscoderorcoder-dind.at once;
runmode.Resolveonly checks--local, andsandbox listisstrictly either/or.
--mount/--volume/--port/--yesonsandbox createwithoutnoting they apply to local sandboxes only.
sandbox listcolumn isCREATOR, notCREATED BY.Happy to take that on in a separate PR if it's wanted.
Stack
dylan/amika-cli-skill#THIS← you are heredylan/ssh-impl-no-relayAdd theamikadsandbox daemon and the no-relay WebSocket SSH path #316dylan/no-ssh-keygen-yet-fixFix the managed sshd port, addamika scpv2, and scope SSH sessions per control plane #321dylan/ssh-websocket-code-reviewResolve SSH relay review annotations and document the connect-token round trip #322