CLI Reference — MIOSA Docs

The miosa CLI (@miosa/cli) is the command-line entry point for MIOSA. It manages computers, sandboxes, deployments, data services, and AI agents — all from your terminal.

Install

Verify the install:

miosa --version

Configuration

Config is stored at ~/.miosa/config.toml:

api_url = "https://api.miosa.ai/api/v1"
api_key = "msk_..."

Precedence: CLI flag --api-key → MIOSA_API_KEY env var → config file → interactive prompt.

Environment variable	Description
`MIOSA_API_KEY`	API key (overrides config file)
`MIOSA_BASE_URL`	Custom API endpoint
`MIOSA_DEBUG=1`	Enable verbose debug output

Command Reference

Getting Started

Authenticate with your MIOSA API key. Saves the key to ~/.miosa/config.toml.

Get an API key from miosa.ai/settings/api-keys.

miosa login
miosa login --api-key msk_yourkey
echo "msk_yourkey" | miosa login   # CI/non-TTY

`miosa logout`

Remove the stored API key from ~/.miosa/config.toml.

`miosa whoami`

Print the currently authenticated user, tenant, and plan.

miosa whoami

`miosa status`

Show auth state, endpoint, tenant, plan, credit balance, and active resource counts.

miosa status

`miosa doctor`

Run environment diagnostics — checks auth, API reachability, CLI version, and shell integration.

miosa doctor

`miosa config [get|set|unset] [key] [value]`

Read or write values in ~/.miosa/config.toml.

miosa config get api_url
miosa config set api_url https://your-instance.ai/api/v1
miosa config unset api_url

`miosa up`

Start the local development environment. Equivalent to running miosa dev with sensible defaults — watches for changes, forwards tunnels, and tails logs.

miosa up
miosa up --port 3000

Computers

`miosa computer create [--image img] [--name name] [--size size]`

Provision a new cloud computer.

miosa computer create
miosa computer create --name dev-box --image ubuntu-22.04 --size medium
miosa computer create --image debian-12 --size large --json

Flag	Description
`--name <name>`	Human-readable name
`--image <image>`	OS image slug (default: `ubuntu-22.04`)
`--size <size>`	`small`, `medium`, `large` (default: `medium`)
`--json`	Output as JSON

`miosa computer list [--json]`

List all computers with their state, image, and last-seen time.

miosa computer list
miosa computer list --json | jq '.[].name'

`miosa computer get <name-or-id> [--json]`

Show details for a specific computer including live telemetry.

miosa computer get dev-box
miosa computer get abc12345 --json

`miosa computer delete <name-or-id> [-f]`

Delete a computer. Prompts for confirmation unless -f.

miosa computer delete dev-box
miosa computer delete abc12345 -f

`miosa computer start <name-or-id>`

Start a stopped computer.

miosa computer start dev-box

`miosa computer stop <name-or-id>`

Stop a running computer.

miosa computer stop dev-box

`miosa computer screenshot <name-or-id> [--out file]`

Capture a screenshot of the computer’s desktop and save it locally.

miosa computer screenshot dev-box
miosa computer screenshot dev-box --out screen.png

`miosa computer apps <name-or-id>`

List running applications on the computer’s desktop.

miosa computer apps dev-box

`miosa computer open <name-or-id>`

Open the computer’s desktop stream in your browser.

miosa computer open dev-box

`miosa computer exec <name-or-id> <cmd> [args...]`

Run a command on the computer non-interactively. Streams stdout/stderr and exits with the remote exit code.

miosa computer exec dev-box npm test
miosa computer exec dev-box ls -- -la /tmp
miosa computer exec dev-box make build --cwd /project --timeout 10m
miosa computer exec dev-box server.js --env NODE_ENV=production --env PORT=8080

Flag	Description
`--cwd <dir>`	Working directory on the computer
`--env KEY=VAL`	Environment variable (repeatable)
`--timeout <duration>`	e.g. `30s`, `2m`, `1h` (default: `5m`)

`miosa computer files <name-or-id> <path>`

List files at a path on the computer.

miosa computer files dev-box /home/user
miosa computer files dev-box /tmp -la

Interactive

`miosa shell <name-or-id> [--cmd "..."]`

Open an interactive PTY terminal on a computer. Exits with the remote shell’s exit code.

miosa shell dev-box
miosa shell dev-box --cmd "htop"

`miosa watch <name-or-id>`

Stream live telemetry and events from a computer.

miosa watch dev-box

`miosa agent start <name-or-id> "<task>"`

Dispatch an AI agent task on a computer. Streams thoughts, tool calls, and results in real time.

miosa agent start dev-box "run the test suite and fix any failures"
miosa agent start dev-box "update all npm dependencies" --steps 20
miosa agent start dev-box "profile the API and find bottlenecks" --timeout 600000

Flag	Description
`--model <model>`	Model override (e.g. `qwen3:32b`)
`--steps <n>`	Max agent steps (default: `10`)
`--timeout <ms>`	Timeout in milliseconds (default: `300000`)
`--tools <list>`	Comma-separated tool list (default: `exec,fs`)

`miosa agent ls <name-or-id>`

List all agent sessions on a computer.

miosa agent ls dev-box
miosa agent ls dev-box --json

`miosa agent get <name-or-id> <session-id>`

Show details and current state for an agent session.

miosa agent get dev-box sess_abc123

`miosa agent task <name-or-id> <session-id> "<task>"`

Send an additional task to a running agent session.

miosa agent task dev-box sess_abc123 "also update the README"

`miosa agent stop <name-or-id> <session-id>`

Stop a running agent session.

miosa agent stop dev-box sess_abc123

`miosa agent history <name-or-id> <session-id>`

Print the full message history for an agent session.

miosa agent history dev-box sess_abc123
miosa agent history dev-box sess_abc123 --json

Sandboxes

`miosa sandbox create [--image img] [--name name]`

Create a new sandbox.

miosa sandbox create
miosa sandbox create --name my-sandbox --image debian-12-sandbox-v8

Flag	Description
`--name <name>`	Human-readable name
`--image <image>`	Sandbox image slug (default: `debian-12-sandbox-v8`)
`--json`	Output as JSON

`miosa sandbox list [--json]`

List all sandboxes with their state and image.

miosa sandbox list
miosa sandbox list --json | jq '.[].id'

`miosa sandbox exec <id> <cmd> [args...]`

Execute a command inside a sandbox. Streams stdout/stderr and returns the exit code.

miosa sandbox exec sb_abc123 python main.py
miosa sandbox exec sb_abc123 npm test --timeout 5m

`miosa sandbox run <id> "<code>"`

Run a code snippet directly inside a sandbox.

miosa sandbox run sb_abc123 "print('hello')"
miosa sandbox run sb_abc123 "import sys; print(sys.version)"

`miosa sandbox write-file <id> <remote-path> <local-file>`

Write a local file into the sandbox filesystem.

miosa sandbox write-file sb_abc123 /app/main.py ./main.py
miosa sandbox write-file sb_abc123 /app/config.json ./config.json

`miosa sandbox read-file <id> <remote-path>`

Read a file from the sandbox filesystem and print it to stdout.

miosa sandbox read-file sb_abc123 /app/output.txt
miosa sandbox read-file sb_abc123 /var/log/app.log > local.log

`miosa sandbox upload <id> <local-path> <remote-path>`

Upload a file or directory to the sandbox.

miosa sandbox upload sb_abc123 ./dist /app/dist
miosa sandbox upload sb_abc123 ./data.csv /tmp/data.csv

`miosa sandbox download <id> <remote-path> [local-path]`

Download a file or directory from the sandbox.

miosa sandbox download sb_abc123 /app/output.json ./output.json
miosa sandbox download sb_abc123 /tmp/results ./results/

`miosa sandbox logs <id> [--follow]`

Stream logs from a sandbox.

miosa sandbox logs sb_abc123
miosa sandbox logs sb_abc123 --follow

Deploy

`miosa deploy [--name name] [--env ENV=VAL]`

Deploy the current directory. Detects the framework automatically.

miosa deploy
miosa deploy --name my-app
miosa deploy --env NODE_ENV=production --env PORT=8080
miosa deploy --region us-east

Flag	Description
`--name <name>`	Deployment name (defaults to directory name)
`--env KEY=VAL`	Environment variable (repeatable)
`--region <region>`	Target region
`--json`	Output as JSON

`miosa deployments list [--json]`

List all deployments.

miosa deployments list
miosa deployments list --json | jq '.[].name'

`miosa deployments get <name-or-id>`

Show details for a deployment.

miosa deployments get my-app

`miosa deployments logs <name-or-id> [--follow]`

Stream logs for a deployment.

miosa deployments logs my-app
miosa deployments logs my-app --follow

`miosa deployments restart <name-or-id>`

Restart a deployment.

miosa deployments restart my-app

`miosa services list`

List all services attached to deployments.

miosa services list

`miosa domains list`

List all custom domains.

miosa domains list

`miosa domains add <deployment> <domain>`

Attach a custom domain to a deployment.

miosa domains add my-app app.example.com

`miosa domains remove <deployment> <domain>`

Remove a custom domain.

miosa domains remove my-app app.example.com

Data

`miosa databases list`

List all managed databases.

miosa databases list
miosa databases list --json

`miosa databases create [--name name] [--engine engine]`

Provision a managed database.

miosa databases create --name app-db --engine postgres
miosa databases create --name cache --engine redis

Flag	Description
`--name <name>`	Database name
`--engine <engine>`	`postgres` or `redis`

`miosa databases get <name-or-id>`

Show connection details and status for a database.

miosa databases get app-db

`miosa storage list`

List all object storage buckets.

miosa storage list

`miosa storage create <name>`

Create a new storage bucket.

miosa storage create my-bucket

`miosa volumes list`

List all persistent volumes.

miosa volumes list

`miosa volumes create <name> [--size size]`

Create a persistent volume.

miosa volumes create app-data --size 10gb

Platform

`miosa functions list`

List all serverless functions.

miosa functions list

`miosa functions deploy <path>`

Deploy a function from a local file or directory.

miosa functions deploy ./functions/handler.ts

`miosa cron list`

List all scheduled cron jobs.

miosa cron list

`miosa cron create "<schedule>" "<cmd>"`

Create a cron job using a standard cron expression.

miosa cron create "0 * * * *" "miosa sandbox exec sb_abc123 python report.py"

`miosa webhooks list`

List all registered webhooks.

miosa webhooks list

`miosa webhooks create --url <url> --events <events>`

miosa webhooks create --url https://example.com/hook --events computer.started,computer.stopped

`miosa checkpoints list <name-or-id>`

List checkpoints (snapshots) for a computer.

miosa checkpoints list dev-box

`miosa snapshot <name-or-id> [--name name]`

Create a snapshot of a computer or sandbox.

miosa snapshot dev-box
miosa snapshot dev-box --name before-upgrade

`miosa network-policy list`

List network policies.

miosa network-policy list

`miosa network-policy create --name <name> --rule <rule>`

Create a network policy rule.

miosa network-policy create --name allow-http --rule "allow:80,443"

`miosa api-keys list`

List all API keys for the current tenant.

miosa api-keys list
miosa api-keys list --json

`miosa api-keys create [--name name] [--scopes scopes]`

Create a new API key.

miosa api-keys create --name ci-key --scopes computers:read,sandboxes:write

`miosa api-keys revoke <id>`

Revoke an API key.

miosa api-keys revoke key_abc123

Workflow

`miosa dev [--port n]`

Start a local development session with hot reload, tunnel forwarding, and log tailing.

miosa dev
miosa dev --port 3000

`miosa run <script>`

Run a script defined in miosa.json or package.json.

miosa run build
miosa run test

`miosa link [name-or-id]`

Link the current directory to a MIOSA computer or deployment. Writes a .miosa config file.

miosa link
miosa link dev-box

`miosa pull <name-or-id> [path]`

Pull files from a computer or deployment into the current directory.

miosa pull dev-box /app/dist
miosa pull my-deploy .

`miosa tunnel open <name-or-id> --port <n>`

Expose a computer port publicly via a MIOSA tunnel.

miosa tunnel open dev-box --port 3000
miosa tunnel open dev-box --port 8080 --name my-app --watch

Flag	Description
`--port <n>`	Port to expose (required)
`--name <slug>`	Optional tunnel name
`--watch`	Stay open and stream live events

`miosa tunnel list <name-or-id>`

List active tunnels on a computer.

`miosa tunnel close <name-or-id> <slug>`

Revoke a tunnel.

`miosa mcp serve [--port n]`

Start a local MCP (Model Context Protocol) server that exposes MIOSA resources to AI tools.

miosa mcp serve
miosa mcp serve --port 8765

`miosa cp <src> <dst>`

Copy files between local and remote. Use host:/path notation for remote paths.

# Upload
miosa cp ./app.tar.gz dev-box:/tmp/
miosa cp -r ./dist dev-box:/var/www/html/

# Download
miosa cp dev-box:/var/log/app.log ./
miosa cp dev-box:/home/user/report.pdf ~/Downloads/

Flags: -r / --recursive for directories.

Exit Codes

Code	Meaning
`0`	Success
`1`	User error (bad arguments, resource not found, etc.)
`2`	Network error
`3`	Authentication / authorization error
`4`	Server error

Troubleshooting

“No API key configured” — Run miosa login.

“Computer not found” — Check miosa computer list for the correct name or ID.

“Insufficient credits” — Top up at miosa.ai/billing.

Network errors — Check your connection. Enable debug output:

MIOSA_DEBUG=1 miosa computer list

Custom endpoint (self-hosted):

MIOSA_BASE_URL=https://your-instance.ai miosa computer list