The MIOSA CLI is the canonical terminal workflow for sandbox development, application publishing, exact release promotion, deployment proof, managed databases, Computers, and OpenComputers.

Registry version verified on July 24, 2026: @miosa/cli@1.1.9.

Install

npm install --global @miosa/cli@latest
miosa version

Use the Node CLI distributed through npm. If another executable named miosa is installed, verify which binary your shell resolves:

command -v miosa
miosa version

Authenticate

Browser login is the normal interactive path:

miosa login
miosa whoami

You can also provide a user API key:

miosa login --api-key msk_u_...

For automation, avoid exposing the key in process arguments:

printf '%s' "$MIOSA_API_KEY" | miosa login --stdin

Discover the current contract

The installed binary is authoritative for command names and options:

miosa --help
miosa command-overview
miosa capabilities --json
miosa <command> --help

miosa capabilities --json is designed for agents and automation. It reports supported resources, workflows, command recipes, and machine-readable capability metadata.

Scope and context

Every mutation must resolve an unambiguous organization, workspace, application, and environment where those scopes apply.

miosa context save personal
miosa context use personal
miosa config ls
miosa whoami

One-off scope overrides are available globally:

miosa --organization <organization> --workspace <workspace-id> status --json

Environment variables can provide the same defaults:

export MIOSA_ORGANIZATION=<organization-slug-or-id>
export MIOSA_WORKSPACE=<workspace-id>

Diagnose the local CLI

miosa doctor --json
miosa status --json

Use --debug to include request IDs and backend error details:

miosa --debug sandbox list --json

Global output controls:

Inspect and plan a local application

The high-level app workflow is the safest path for an agent or human updating an existing production app:

miosa app inspect . --json
miosa app plan . --goal deploy --json
miosa app link . --app <deployment-id>
miosa app pull . --json
miosa app preview . --json

Linking writes the application identity to .miosa.json. Later publishes can resolve the same deployment instead of accidentally creating a duplicate.

Create a sandbox

miosa sandbox create 
  --template nextjs 
  --name my-app 
  --timeout 1h 
  --wait 
  --json

Sandboxes are persistent by default. Pause or stop preserves the filesystem according to sandbox policy.

miosa sandbox list --json
miosa sandbox show <sandbox-id> --json
miosa sandbox pause <sandbox-id> --json
miosa sandbox resume <sandbox-id> --json
miosa sandbox stop <sandbox-id> --json
miosa sandbox destroy <sandbox-id> --force --json

Files and commands

miosa sandbox exec <sandbox-id> -- npm test
miosa sandbox write-file <sandbox-id> /workspace/config.json ./config.json
miosa sandbox read-file <sandbox-id> /workspace/config.json
miosa sandbox upload-dir <sandbox-id> ./app /workspace
miosa sandbox download <sandbox-id> /workspace/report.pdf --output ./report.pdf
miosa sandbox logs <sandbox-id>

Use -- before a sandbox command that contains flags:

miosa sandbox exec <sandbox-id> -- bash -lc "cd /workspace && npm run build"

Services, environment, and previews

miosa sandbox service --help
miosa sandbox env --help
miosa sandbox db --help
miosa sandbox preview <sandbox-id> --port 3000 --wait --json
miosa sandbox doctor <sandbox-id> --json

Subresource command groups evolve independently. Run the group’s --help before constructing automated mutations.

Sandbox snapshots

miosa sandbox snapshot <sandbox-id> --name "before migration" --json
miosa sandbox snapshots list <sandbox-id> --json
miosa sandbox snapshots get <sandbox-id> <snapshot-id> --json
miosa sandbox create --snapshot <snapshot-id> --name restored-copy --wait --json
miosa sandbox snapshots delete <sandbox-id> <snapshot-id> --json
miosa sandbox fork <sandbox-id> --json

Snapshots cover the sandbox VM. Managed databases, object storage, connectors, and external services have independent state.

Publish a new App Engine deployment

miosa sandbox publish <sandbox-id> 
  --name my-app 
  --slug my-app 
  --path /workspace 
  --run-command "npm run start" 
  --port 3000 
  --docker-deploy 
  --wait 
  --json

The response contains the deployment ID, candidate release, operation evidence, and API-selected public_url. Always use the returned URL.

Publish an update to an existing deployment

Use --app for every update to an existing application:

miosa sandbox publish <sandbox-id> 
  --app <deployment-id> 
  --path /workspace 
  --run-command "npm run start" 
  --port 3000 
  --docker-deploy 
  --wait 
  --json

This preserves the deployment identity, stable URL, database bindings, environment, release history, and rollback path.

Inspect, promote, and roll back releases

miosa releases list <deployment-id> --json
miosa releases get <deployment-id> <release-id> --json
miosa releases promote-release <deployment-id> <release-id> --yes --json
miosa releases rollback <release-id> --app <deployment-id> --yes --json

For the high-level linked-app workflow:

miosa app promote <release-id> . --yes --json
miosa app rollback <release-id> . --yes --json

Promotion selects one exact immutable release. A failed candidate must not replace the active healthy production release.

Prove production

miosa deploy prove <deployment-id> --json
miosa docker-deploy doctor <deployment-id> --probe-path / --json

Healthy metadata alone is insufficient. Proof must reconcile the selected release, running artifact, runtime placement, route, data bindings, required capabilities, and public HTTP response.

Managed databases

miosa databases list --json
miosa databases create --engine postgresql --name app-production --wait --json
miosa databases get <database-id> --json
miosa databases metrics <database-id> --json
miosa databases stop <database-id> --json
miosa databases start <database-id> --json
miosa databases restart <database-id> --json
miosa databases connect <database-id>
miosa databases logs <database-id>
miosa db backup <database-id> --json
miosa db restore <database-id> --backup <backup-id> --force --json

Poll miosa databases get or use the durable operation returned by the mutation before binding traffic to a restarted database.

Capability contracts and durable operations

The capability-gated workflow is shipped as additive command families around the existing happy path:

miosa blueprint validate ./miosa.app.yml --json
miosa blueprint show ./miosa.app.yml --json

miosa changes plan <release-id> . --json
miosa changes approve <plan-id> --actor <identity> --json
miosa changes show <plan-id> --json
miosa changes apply <plan-id> --json

miosa placement show . --json
miosa policy check . --json
miosa drift detect <plan-id> . --json
miosa drift reconcile <plan-id> . --json
miosa evidence list . --json
miosa evidence show <receipt-id> . --json
miosa incidents list . --json
miosa wait operation <operation-id> --json
miosa memory record "Approved production rollout" . --json
miosa memory list . --json

Run each family’s --help for its exact positional arguments and current options. Plans and receipts are immutable records. Applying a plan must target its exact candidate release and preserve its approval, evidence, and idempotency state.

Templates

Use catalog for canonical product templates, shapes, image generations, and readiness:

miosa templates catalog --product sandbox --json
miosa templates readiness miosa-sandbox --json

Use list, get, create, builds, and delete for tenant-visible sandbox templates:

miosa templates list --json
miosa templates get <template-id> --json
miosa templates create --name my-env --dockerfile ./Dockerfile --json

Computers and OpenComputers

miosa computers list --json
miosa computers create --name browser-worker --json
miosa computers show <computer-id> --json
miosa computers vnc <computer-id>

miosa opencomputers list --json
miosa opencomputers connect my-mac --platform macos
miosa ssh my-mac
miosa exec my-mac "npm test"
miosa cp ./report.pdf my-mac:/tmp/report.pdf

Agent runs and runtime configuration

miosa runs list --json
miosa runs show <run-id> --json
miosa runs activity <run-id> --stream
miosa runs files <run-id> --json
miosa runs download-file <run-id> <file-id> --output ./result.pdf
miosa runs cancel <run-id> --json

miosa agent-runtime-profiles --help
miosa runtime-env --help
miosa connectors --help

API tokens

API-token management lives under auth token:

miosa auth token --help

Built-in application auth lives under auth project-auth:

miosa auth project-auth --help

API key operations live under miosa auth token. Built-in application authentication lives under miosa auth project-auth.

Shell completion

miosa completion zsh > ~/.zsh/completions/_miosa
miosa completion bash > ~/.local/share/bash-completion/completions/miosa

Update

miosa update
miosa version

The npm package is the authoritative CLI distribution. Do not compare its version number with a different implementation installed under the same command name.

Next