Skip to main content
TOSE
VIEN

TOSE CLI

TOSE CLI

The TOSE CLI (@tosesh/tose, version 0.2.0 on npm, published 2026-11-03) deploys and operates apps from a terminal, a script or a coding agent. Agents that speak MCP can also connect to the TOSE MCP server at https://app.tose.sh/mcp with OAuth instead of an API key.

Install

Needs Node.js and npm. Check the installed version against the npm release list.

npm install -g @tosesh/tose
tose --version

Release history on npm

Sign in without exposing the key

Create an API key in workspace Settings → API Keys (owners and admins). The CLI reads it from TOSE_API_KEY, so it never has to appear in a prompt, a command line, a URL, a log or a commit. Keys are for one workspace and are revoked or expire as set there.

export TOSE_API_KEY=...   # set it in your shell or secret store, never in a prompt, URL or commit
tose whoami --json

Create an API key in the dashboard

Plan, execute, verify, recover

The same loop works for a person and for an agent. Every command takes --json and returns one JSON document.

tose doctor my-workspace/my-app --json
tose deploy my-workspace/my-app --dry-run --json
tose deploy my-workspace/my-app --wait --non-interactive --json
tose status my-workspace/my-app --json
tose logs my-workspace/my-app -n 100
  1. Plan: doctor checks auth, git, server, port, quota, health and DNS/SSL; deploy --dry-run prints the plan and changes nothing.
  2. Execute: deploy --wait blocks until the deployment is running with every pod ready. --non-interactive fails instead of prompting.
  3. Verify: status and logs show pod health and output. Check the JSON before reporting success.
  4. Recover: Read the build log and the error, fix the cause and run again. An empty wallet refuses a new deploy (HTTP 402): ask a person to top up, do not retry.

Stop and ask a person first

Commands that remove or stop something need confirmation, and --yes is required without a terminal. An agent should ask before it runs any of these: tose down, tose env rm, tose domain rm, tose disk delete.

Scopes

A key without scopes has full access to its workspace. The API can create a scoped key (Beta); the dashboard form and the CLI cannot set scopes yet, and a request outside the scopes fails with insufficient_scope.

Skills for agents

Since 0.2.0 the CLI lists and installs agent skills from the public catalogue and checks the sha256 digest of every file before it installs them. The catalogue is a set of documents, not an MCP server.

tose skills list
tose skills install deploy-nextjs-to-tose

Skills catalogue (JSON)

Let an agent discover the commands

tose capabilities --json describes commands, flags, risk levels and versions for the installed version, so an agent does not need to guess.

tose capabilities --json

Next