The MIOSA CLI

miosa covers the whole platform: sandboxes and computers, files and previews, agents and their runs, deployments, databases, storage, API keys, webhooks, billing and the organization you work in.

Quick start

npm i -g @miosa/cli               # or Homebrew, the install script, or a release archive
miosa --version                   # prints 2.3.1
miosa login                       # browser device-code sign in
miosa whoami                      # user, organization, plan and scopes
miosa create my-box --wait        # provision a sandbox
miosa exec my-box -- echo hello   # run a command
miosa destroy my-box --yes

Use the CLI from agents

The CLI is not only for humans. OSA, MIOSA’s open-source agent, runs shell commands, so it can drive miosa from your machine or from a MIOSA computer. osa run "..." runs it headless with no TUI. Any agent with shell access can do the same, and drive the entire platform with miosa: it covers every resource the API and the SDKs expose, not just a tool surface, and it composes with the shell and the tools the agent already has.

• Install inside a sandbox or CI. npm i -g @miosa/cli is the fastest path in a container or CI job. Sandbox images ship Node, so a fresh agent machine has the CLI in one command.
• Authenticate with a key. Set MIOSA_API_KEY and every command is authenticated with no browser. Never pass a key as an argument.
• Get JSON and exit codes. Add --json for machine-readable output and branch on the exit code. exec and ssh exit with the remote command’s status.

export MIOSA_API_KEY="msk_u_..."
npm i -g @miosa/cli

# An agent provisioning, using and cleaning up a machine, all scriptable
ID=$(miosa create agent-box --size small --ttl 1h --wait --json | jq -r .id)
miosa exec "$ID" -- npm ci
miosa preview create "$ID" 3000 --visibility public --json | jq -r .url
miosa destroy "$ID" --yes

An agent running in Claude Code or Codex with shell access uses exactly these commands: provision a sandbox, run a build, publish a preview, read the JSON, clean up. No MCP setup required.

When the CLI beats MCP

Use the CLI when the agent already has a shell. It reaches the whole platform rather than one tool surface, its output is scriptable and composes with jq, pipes and files, and miosa api <METHOD> <path> covers any endpoint the high-level commands do not. Use MCP when the client has no shell, or when you want the model to choose tools rather than write commands. See CLI or MCP: which to use.

Command groups

Every top-level command, grouped the way the CLI organises them.

Machine arguments

Anywhere a sandbox is expected you may give its name, its id, current (set with miosa use) or self (inside a sandbox). Commands that act on a computer take --computer.

miosa exec my-box -- npm test      # by name
miosa exec sbox_abc123 -- npm test # by id
miosa use my-box                   # then omit the name
miosa exec -- npm test

Global flags

These apply to every command.

--api-key string      API key (overrides MIOSA_API_KEY and config)
--api-url string      API base URL (overrides MIOSA_BASE_URL and config)
--profile string      Config profile to use (MIOSA_PROFILE)
--org string          Organization to bill for this command (MIOSA_ORG)
--json                Machine-readable JSON (same as -o json)
-o, --output string   text (default) or json (MIOSA_OUTPUT)
-q, --quiet           Suppress informational output
--retries int         Retries on 429 and transient 5xx (default 3, MIOSA_RETRIES)
--timeout int         Request timeout in seconds; for exec and ssh the command timeout
--no-update-notice    Silence the new-version notice

Exit codes

miosa exec and miosa ssh exit with the remote command’s status.