CLI - Tinycloud

Run the workspace CLI as pnpm tiny <command>. The underlying entry point is tools/cli/src/main.ts.

The CLI never starts a control plane or an application runtime. All planning, deployment, status, and log commands target the configured remote server.

Global behavior

Every command accepts these global flags:

Flag	Meaning
`--api <url>`	control-plane URL
`--token <token>`	bearer token for this invocation
`--cwd <path>`	app directory containing `tiny.yaml`
`--json`	emit one versioned JSON result on stdout
`--idempotency-key <key>`	stable key for a mutating operation that supports it

Configuration is resolved from flags, then TINY_API_URL / TINY_TOKEN, then the current saved profile. TINY_CONFIG changes the credential-file path from its default, ~/.tiny/credentials.json. With --json, progress stays on stderr. Commands do not prompt when stdin is not a TTY.

tiny secrets set accepts a secret from a prompt or piped stdin. The value is deliberately not accepted as a command-line argument — that would put it in shell history and the process table.

Authentication and setup

Command	Behavior
`login --api <url> [--token <token>] [--profile <name>]`	store a control-plane profile
`logout [--profile <name>]`	remove a saved profile
`whoami`	show the current control plane and its target capabilities
`org create --api <url> --slug <slug> --owner <email> [--name <display>]`	bootstrap an organization and save its session

App authoring and deployment

Command	Behavior
`init [name] [--owner <email>] [--force]`	write a starter `tiny.yaml`
`validate`	parse, normalize, and validate the manifest locally
`doctor`	check credentials, manifest, entrypoint, migrations, and target reachability
`plan [--env <name>]`	upload an immutable artifact and calculate a non-mutating plan
`deploy [--env <name>] [--yes] [--no-wait] [--wait <seconds>]`	plan, enqueue a deployment, and watch it finish
`rollback <deployment-id>`	switch traffic to an earlier deployment
`preview create [--name <name>] [--ttl <duration>]`	create an isolated expiring environment
`preview delete <environment-id>`	remove a preview environment

About `--yes`

--yes passes approval intent with the deployment request. It does not bypass role or policy checks. In non-interactive use, a plan with required approvals fails with APPROVAL_REQUIRED unless --yes is supplied. See Approvals.

About `deploy` and waiting

deploy returns when the deployment reaches a terminal state, because the API answers 202 and a worker builds and rolls out afterwards — a deploy that returned is not a deploy that happened. It reports how the artifact came to exist (Built in 12.4s, or Reused a cached build when the content-addressed build was already in the cache), and exits non-zero if the deployment failed, repeating the deployer’s own reason and remediation.

Flag	Effect
(default)	wait for a terminal state
`--wait <seconds>`	bound the watch; exhausting it is not a failure — the command warns and exits `0` with the deployment still running
`--no-wait`	return as soon as the request is accepted; what a fire-and-forget script wants

In --json mode the single result object gains a build field ({ artifactUri, cached, durationMs }) whenever a build ran.

What gets uploaded

Artifacts omit .git, node_modules, .tiny, common caches, and credential-looking files. Add repository-specific patterns to .tinyignore.

Upload limit	Value
Files	5,000
Total size	50 MiB
Per file	10 MiB

Inspection and governance

Command	Behavior
`status`	list apps and their current lifecycle state
`logs [app] [--since 1h] [--limit 100]`	read bounded logs from the latest deployment
`open [app] [--env production]`	print an environment URL
`access list [--app <id-or-slug>]`	list bindings
`access grant <subject> [--role user] [--app <id-or-slug>]`	add or replace a binding
`access revoke <subject> [--app <id-or-slug>]`	remove a binding
`secrets set <name>`	read a value from the terminal or stdin and create a new version
`secrets list`	list names and creation times; values are never returned
`capabilities list`	list the operation catalog
`capabilities request <operation> --connection <name> [--app <id-or-slug>]`	request a grant
`archive [app]`	snapshot resources and take the app offline
`restore [app]`	restore an archived app; deploy again to serve traffic
`delete [app] --confirm <exact-slug>`	schedule deletion after the seven-day grace window

When an optional app reference is omitted, the CLI reads metadata.name from the current directory’s tiny.yaml.

Exit codes

Code	Meaning
0	success
2	command usage
3	authentication
4	validation
5	policy or approval
6	not found
7	interaction required
8	conflict
9	provider or control-plane unavailable

Scripts should branch on these rather than on message text. Codes 5 and 7 in particular mean “a human has to do something”, not “this failed”.

​Global behavior

​Authentication and setup

​App authoring and deployment

​About --yes

​About deploy and waiting

​What gets uploaded

​Inspection and governance

​Exit codes

Global behavior

Authentication and setup

App authoring and deployment

About `--yes`

About `deploy` and waiting

What gets uploaded

Inspection and governance

Exit codes