Reference · CLI

CLI reference

Every grotte subcommand, argument, and option. Generated from grotte --help — re-run that against your installed version if you suspect drift.

Install

bash

npm install -g @grotte/cli

Latest published version: see @grotte/cli on npm. Check yours with grotte --version.

Authentication

Most commands require auth. Two paths:

bash

grotte auth login                       # browser flow (recommended)
grotte auth login --key grt_...         # non-interactive, sandbox scope only

The --key shortcut is useful in CI: paste a team API key and run sandbox-scoped commands without a browser. Template + team-management commands still require the browser flow — they need a personal access token, not a team API key.

`grotte auth`

Authentication commands.

`grotte auth login`

Option	Description
`--key <apiKey>`	Log in non-interactively with a team API key (`grt_…`). Sandbox-scoped commands work; template/team-management commands still require the browser flow.

`grotte auth logout`

Log out of the CLI. Clears ~/.grotte/config.json.

`grotte auth info`

Print information about the current logged-in user (email, team, token scope).

`grotte auth configure`

Interactive prompt to update saved credentials.

`grotte sandbox` · alias `sbx`

Work with sandboxes.

`grotte sandbox create [template]` · alias `cr`

Create a sandbox and connect a terminal to it.

Option	Description
`-p, --path <path>`	Change root directory where the command is executed.
`--config <grotte-toml>`	Path to the GROTTE config toml. Default `./grotte.toml`. (The new build system does not use config files.)
`-d, --detach`	Create the sandbox without attaching a terminal.
`-j, --json`	Print the creation result as JSON (implies `--detach`).

`grotte sandbox connect <sandboxID>` · alias `cn`

Attach a terminal to an already-running sandbox.

`grotte sandbox info <sandboxID>` · alias `in`

Show information for a sandbox.

Option	Description
`-f, --format <format>`	Output format — `json` or `pretty`.

`grotte sandbox list` · alias `ls`

List sandboxes (running by default).

Option	Description
`-s, --state <state>`	Filter by state — `running`, `paused`. Defaults to `running`.
`-m, --metadata <metadata>`	Filter by metadata, e.g. `key1=value1`.
`-l, --limit <limit>`	Limit results (default 1000, `0` = no limit).
`-f, --format <format>`	Output format — `json` or `pretty`.

`grotte sandbox kill [sandboxIDs...]` · alias `kl`

Kill one or more sandboxes immediately.

Option	Description
`-a, --all`	Kill all sandboxes.
`-s, --state <state>`	With `--all`, filter by state. Defaults to `running`.
`-m, --metadata <metadata>`	With `--all`, filter by metadata.

`grotte sandbox pause <sandboxID>` · alias `ps`

Pause a sandbox (filesystem state retained).

`grotte sandbox resume <sandboxID>` · alias `rs`

Resume a paused sandbox.

`grotte sandbox logs <sandboxID>` · alias `lg`

Show logs for a sandbox.

Option	Description
`--level <level>`	Filter by level — `DEBUG`, `INFO`, `WARN`, `ERROR`. Higher levels also shown. Default `INFO`.
`-f, --follow`	Stream until the sandbox closes.
`--format <format>`	`json` or `pretty`. Default `pretty`.
`--loggers [loggers]`	Filter by loggers — comma-separated.

`grotte sandbox metrics <sandboxID>` · alias `mt`

Show CPU / RAM / disk metrics.

Option	Description
`-f, --follow`	Stream metrics.
`--format <format>`	`json` or `pretty`. Default `pretty`.

`grotte sandbox exec <sandboxID> <command...>` · alias `ex`

Execute a one-off command in a running sandbox.

Option	Description
`-b, --background`	Run in background and return immediately.
`-c, --cwd <dir>`	Working directory.
`-u, --user <user>`	Run as the specified user.
`-e, --env <KEY=VALUE>`	Set environment variable (repeatable).

`grotte snapshot` · alias `snap`

Manage sandbox snapshots — frozen filesystem state reusable as a template.

`grotte snapshot create <sandboxID>` · alias `cr`

Snapshot a sandbox to a reusable template.

`grotte snapshot list` · alias `ls`

List snapshots.

Option	Description
`-s, --sandbox <sandboxID>`	Filter snapshots by source sandbox ID.
`-f, --format <format>`	`json` or `pretty`.

`grotte snapshot delete <snapshotID>` · alias `rm`

Delete a snapshot.

`grotte template` · alias `tpl`

Manage sandbox templates.

`grotte template create <template-name>` · alias `ct`

Build a Dockerfile (or grotte.template.ts / grotte_template.py) into a sandbox template. The template name must match [a-z0-9-_]+.

Option	Description
`-p, --path <path>`	Change root directory.
`-d, --dockerfile <file>`	Dockerfile path. Defaults to `grotte.Dockerfile` then `Dockerfile`.
`-c, --cmd <start-command>`	Command run when the sandbox starts (as `sudo`).
`--ready-cmd <ready-command>`	Command that must exit `0` for the template to be marked ready.
`--cpu-count <cpu-count>`	CPU count. Default `2`.
`--memory-mb <memory-mb>`	Memory in MB. Must be even. Default `512`.
`--no-cache`	Skip cache when building.

`grotte template list` · alias `ls`

List sandbox templates.

Option	Description
`-t, --team <team-id>`	Team ID. Find it at dashboard?tab=team.
`-f, --format <format>`	`json` or `pretty`.

`grotte template init` · alias `it`

Initialize a new sandbox template using the SDK.

Option	Description
`-p, --path <path>`	Change root directory.
`-n, --name <name>`	Template name.
`-l, --language <language>`	Target language — `typescript`, `python-sync`, `python-async`.

`grotte template delete [template]` · alias `dl`

Delete a sandbox template (and its grotte.toml config). Without [template], deletes the one defined in grotte.toml.

Option	Description
`-p, --path <path>`	Change root directory.
`--config <grotte-toml>`	Path to `grotte.toml`.
`-s, --select`	Select template from an interactive list.
`-t, --team <team-id>`	Team ID.
`-y, --yes`	Skip manual delete confirmation.

`grotte template publish [template]` · alias `pb`

Publish a sandbox template (makes it discoverable + usable by other teams).

Option	Description
`-p, --path <path>`	Change root directory.
`--config <grotte-toml>`	Path to `grotte.toml`.
`-s, --select`	Select from interactive list.
`-t, --team <team-id>`	Team ID.
`-y, --yes`	Skip publish confirmation.

`grotte template unpublish [template]` · alias `upb`

Reverse template publish.

`grotte template migrate`

Migrate a grotte.Dockerfile + grotte.toml to the new Template SDK format (defining a template).

Option	Description
`-d, --dockerfile <file>`	Dockerfile path. Defaults to `grotte.Dockerfile`.
`--config <grotte-toml>`	Path to `grotte.toml`.
`-l, --language <language>`	Target — `typescript`, `python-sync`, `python-async`.
`-p, --path <path>`	Change root directory.

Where to file CLI bugs

GitHub: parallactic-ai/grotte-sdk. Include the version (grotte --version), your platform, and the full command output.

Install

Authentication

grotte auth

grotte auth login

grotte auth logout

grotte auth info

grotte auth configure

grotte sandbox · alias sbx

grotte sandbox create [template] · alias cr

grotte sandbox connect <sandboxID> · alias cn

grotte sandbox info <sandboxID> · alias in

grotte sandbox list · alias ls

grotte sandbox kill [sandboxIDs...] · alias kl

grotte sandbox pause <sandboxID> · alias ps

grotte sandbox resume <sandboxID> · alias rs

grotte sandbox logs <sandboxID> · alias lg

grotte sandbox metrics <sandboxID> · alias mt

grotte sandbox exec <sandboxID> <command...> · alias ex

grotte snapshot · alias snap

grotte snapshot create <sandboxID> · alias cr

grotte snapshot list · alias ls

grotte snapshot delete <snapshotID> · alias rm

grotte template · alias tpl

grotte template create <template-name> · alias ct

grotte template list · alias ls

grotte template init · alias it

grotte template delete [template] · alias dl

grotte template publish [template] · alias pb

grotte template unpublish [template] · alias upb

grotte template migrate