CLI reference
Commands for authentication, sandbox lifecycle, remote execution, agents, and previews.
Run Adria commands on your local computer unless a guide says otherwise. Start with Get started quickly to install the CLI and sign in.
cube --help
cube start --help
cube --versionUse --help on any command for all options supported by your installed version.
Account and repository
| Command | Purpose |
|---|---|
cube login | Sign in and authorize GitHub through a browser |
cube login --no-browser | Sign in with a URL and one-time completion code |
cube logout | Revoke and remove this local Adria login |
cube auth | Show GitHub and agent credential configuration |
cube auth github | Connect or renew GitHub authorization |
cube init | Identify the local GitHub repository in Adria |
cube init --json | Print repository identity and local Git state as JSON |
Sandbox lifecycle
<session> means a branch name or Session UUID. Use UUIDs outside a repository
or when branch names are ambiguous.
| Command | Purpose |
|---|---|
cube start <branch-or-session-id> | Create or resume a Session and enter its shell |
cube connect <session> | Connect to an existing Session, resuming if paused |
cube sessions | List your Sessions; alias: cube ls |
cube sessions --json | Print Sessions as JSON |
cube pause <session> | Stop compute and preserve disk |
cube kill <session> | Permanently delete a Session and its disk |
cube usage --detailed | Show monthly VM time and estimated cost per Session |
Pause and kill return when their request is accepted. Check completion with
cube sessions. cube kill --all deletes all your Sessions and disks across
repositories; use a single Session target to remove only one task.
Start and connect options
| Option | Purpose |
|---|---|
--source-ref origin/release | Choose the starting remote ref for a new branch (start only) |
--tmux work | Create or attach a named remote tmux terminal |
--command 'git status' | Run a remote command without a PTY |
--tty | Allocate a PTY for --command |
--terminal current | Use the current terminal; choices: auto, current, cmux, tmux |
--diagnostics | Print Session details and startup timings |
--timeout 30m | Set the readiness wait; default: 20m |
--ssh-config | Write a five-minute OpenSSH config and print its path |
Run a command directly from your local terminal:
cube connect feature/payments --command 'git status --short'Commands execute in the remote repository. --tmux requires an interactive
shell and cannot be combined with --command. Remote commands are not
automatically replayed after connection loss.
Activity and capture
| Command | Purpose |
|---|---|
cube sessions --json | Show VM lifecycle and individual terminal agent observations |
cube sessions capture <session> off | Disable terminal capture for the Session |
cube sessions capture <session> on | Enable terminal capture on supported images |
Capture records terminal input and output and is enabled by default on supported images. Turning it off stops future collection and does not delete existing data. See logs and agent status for observed state and capture behavior.
SSH and file transfer
cube connect <session> --ssh-config prints the path of a temporary OpenSSH
config. Use it with ssh -F, scp -F, or sftp -F. The access grant expires
after five minutes. See SSH and terminals and
File operations for complete examples.
start and connect also accept OpenSSH forwarding options -L, -R, and -D.
Repository environment files
Run these commands from your local repository. Saved files are reused by new
and resumed computers; use apply to refresh a running one.
| Command | Purpose |
|---|---|
cube env import | Select and save local environment files |
cube env import apps/api/.env | Save a specific repository environment file |
cube env import --dry-run | Preview file paths and key names without uploading |
cube env import --shared apps/api/.env | Publish team defaults with GitHub write access |
cube env list | Show saved paths, key names, and scopes |
cube env apply <session> | Refresh environment files in a running computer |
cube env remove apps/api/.env | Remove personal values for that file |
Personal values override shared defaults. Restart your applications after applying changes. See Environment variables for updates, conflicts, and shared configuration.
Agent setup
| Command | Purpose |
|---|---|
cube auth codex | Save an OpenAI API key for Codex |
cube auth claude | Save an Anthropic API key for Claude Code |
cube auth claude --method setup_token | Save a Claude setup token |
cube auth pi --provider anthropic | Save Pi credentials for a selected provider |
cube auth codex --remove | Disable future delivery of this agent's credential |
cube config import codex --dry-run | Preview settings and resources to import |
cube config import codex --wait | Import and wait for cloud acceptance |
cube config status | Check import progress and readiness |
cube config remove codex | Remove the saved configuration import |
Replace codex with claude or pi for their config commands. See
Coding agents for the difference between credentials and settings.
Ports and desktop
| Command | Purpose |
|---|---|
cube open 3000 --session <session> | Forward an app and open it in your local browser |
cube forward 3000:8080 --session <session> | Forward remote port 3000 to local port 8080 |
cube desktop <session> | Open a supported sandbox's desktop viewer |
cube browser <session> <url> | Open a URL in the sandbox's browser |
cube computer screenshot <session> --output screen.png | Save a desktop screenshot |
Port tunnels need a ready Session and stay active while their command runs. Desktop commands require an image with desktop support. See Networking and tunnels and Computer use.
Updates
Update your installed CLI:
cube updateSet NO_COLOR=1 to disable terminal colors; use the commands' JSON flags where
available for machine-readable output.