Docs · CLI

CLI reference.

Install the remoco binary, sign in through WorkOS, then drive your Workspace infrastructure through api.remoco.dev.

Install and sign in

$ npm install -g @doss-labs/remoco
$ remoco login
Open this URL in your browser:
https://your-authkit-domain/device
Enter code: ABCD-EFGH
Waiting for browser confirmation...

remoco login uses the official WorkOS OAuth 2.0 device authorization flow. The CLI always prints the manual verification URL and user code. When a desktop browser is available, it also opens the one-click confirmation URL.

After confirmation, Remoco verifies the exact WorkOS user, verified email, Organization, current Remoco membership, and tenant binding. The short-lived WorkOS access token is exchanged once for a user-bound pak_ credential. WorkOS access and refresh tokens are never saved by the CLI.

The Remoco credential is written atomically to ~/.remoco/credentials.json. The directory is mode 0700 and the file is mode 0600.

Command	Description
`remoco login`	WorkOS browser confirmation with a manual code fallback. No token paste is required.
`remoco login --token=X [--user=Y --env=staging\|prod]`	Store an existing bearer for CI or an explicit service workflow.
`remoco whoami`	Resolve the current Remoco user, Organization, role, and token limits.
`remoco doctor`	Check credential storage, API reachability, current auth, GCP shell auth, and local tools.

Quickstart

Command	Description
`remoco scaffold [--template=node\|python\|go\|static\|workstation]`	Write a minimal `remoco.yaml` shaped to the current repository.
`remoco up [--no-wait] [--param=key=value]`	Deploy `./remoco.yaml` and wait for the stack to reach a terminal state.
`remoco down [--name=stack-name]`	Destroy the stack named by `./remoco.yaml` or the explicit name.

Workspaces and resources

Command	Description
`remoco list`	List the caller's Workstations.
`remoco init [--purpose=X]`	Provision the caller's primary Workstation.
`remoco start\|stop\|rm <name>`	Resume, suspend, or remove a Workstation.
`remoco expose <alias> --workstation=<name> [--access=private\|public]`	Publish a stable URL for a Workstation service.
`remoco links`	List currently published URLs.
`remoco resources list [--kind=X --all]`	List polymorphic resources. Destroyed resources are hidden unless `--all` is set.
`remoco resources get <id>`	Read one resource.
`remoco resources kinds`	List supported resource kinds.
`remoco create <kind> <name> [--spec='{}' --region=X]`	Create a resource.
`remoco destroy\|suspend\|resume <id>`	Change a resource lifecycle state.

Stacks and projects

Command	Description
`remoco blueprints`	List the versioned stack blueprint catalog.
`remoco stacks list\|get <id> [--yaml]`	List stacks or read one stack. YAML output round-trips to `remoco.yaml`.
`remoco stacks deploy <blueprint> <name> [--version=N --param=k=v]`	Deploy a versioned blueprint.
`remoco stacks destroy <id>`	Destroy a stack and its children.
`remoco stacks diff <a> <b>`	Compare stack roles, kinds, dependencies, specs, and state.
`remoco projects list\|create\|archive`	Manage project groupings inside the current Organization.

Observe

Command	Description
`remoco dashboard`	Show current resource count, state, and burn.
`remoco events tail [--limit=N --kind=X --target=Y --follow]`	Read or stream control-plane events.
`remoco logs <resource-id> [--limit=50 --since=10m \| --follow]`	Open the matching Google Cloud log stream.
`remoco audit [--target=X]`	Legacy alias for filtered events.
`remoco balance`	Read the caller's credit ledger.

Environment

Variable	Default	Meaning
`REMOCO_ENV`	`staging`	Select `staging` or `prod`.
`REMOCO_API_URL`	`https://api.remoco.dev`	Override the staging API base URL.
`REMOCO_API_URL_PROD`	`https://api.remoco.dev`	Override the production API base URL.
`REMOCO_API_TOKEN`	unset	Non-interactive bearer alternative to `remoco login`.

← Getting started Skills reference →