Common commands

The commands you’ll use most. Run nuon --help (or nuon <command> --help) for the full set.

Global flags

These work on every command.

Flag	What it does
`--config <path>`, `-C <path>`	Use a custom config file instead of `~/.nuon`. Can also be set with the `NUON_CONFIG_FILE` env var.
`--output <format>`	Output format: `table` (default), `json`, or `agent`. Can also be set with `NUON_OUTPUT`.
`--read-only`	Block any command that modifies state. Can also be set with `NUON_READ_ONLY=1`.
`--debug`	Print per-request API timing to stderr.

Names and defaults

Flags that take an app, install, component, action, runbook, or branch ID generally accept the resource’s name as well. The -i (install) and -a (app) flags default to the install or app you last selected, so you can usually leave them off.

nuon actions create-run -i customer1 -w pg_status

Authenticate

Command	What it does
`nuon auth login`	Sign in (browser SSO). Run this first.
`nuon auth logout`	Sign out.

Organizations

Command	What it does
`nuon orgs select`	Switch your active org. A new trial account has a single org that’s selected automatically when you log in, so you only need this once you belong to more than one.
`nuon orgs current`	Show the active org.
`nuon orgs api-tokens create --name <name>`	Create a durable API token for the current org (shown once). Requires org admin. Add `--role` (defaults to `org_read_only`; run `nuon roles list` or see Access control) to set the token’s permissions, or `--personal` to issue the token against your own account and its existing roles instead.
`nuon orgs api-tokens list`	List the current org’s API tokens.
`nuon orgs api-tokens delete --id <token-id>`	Revoke an API token.
`nuon orgs update-user-role --user-id <id> --role <role>`	Change an org member’s role (run `nuon roles list` or see Access control). Requires org admin.

Apps & config

Command	What it does
`nuon apps create --name <name>`	Create an app template in the control plane.
`nuon apps validate [dir]`	Validate an app config directory (default: the current directory). Requires login, and it looks up the app by the directory’s name, so an app with that name must exist. Run `nuon apps create` first.
`nuon apps list`	List your apps.
`nuon apps select`	Set your active app.

App branches

These subcommands operate on the selected app. Use nuon apps select to choose it; commands that accept --app-id can use the ID from nuon apps list when you do not want to rely on the selected app. nuon apps branches is a deprecated alias; use nuon branches.

Command	What it does
`nuon branches sync --file <path>`	Reconcile branch settings from a TOML file or directory. Directory mode can propose deleting remote branches missing locally; a single file never deletes others.
`nuon branches list`	List the selected app’s branches.
`nuon branches get --branch-id <branch-id>`	Show a branch and its install groups.
`nuon branches create --name <name>`	Create a branch without syncing a config file.
`nuon branches trigger --branch-id <branch-id>`	Start a real branch run. Add `--force` to rebuild every component. Add `--run-type` (`pr`, `tag`, or `commit`) and `--run-ref` to deploy a specific source.
`nuon branches preview --branch-id <branch-id> --git-ref <ref> --mode plan-only`	Preview a committed Git ref. Use `--pr-number` for a pull request; `--mode` also accepts `apply` or `build-only`.
`nuon branches runs --branch-id <branch-id>`	List the selected app’s branch runs and open one in the workflow TUI.
`nuon branches delete --branch-id <branch-id> --confirm`	Delete a branch.

nuon apps sync and nuon sync are deprecated: app config ships through a branch file synced once with nuon branches sync, then a push to the tracked git branch. Once they are turned off for your org, running nuon apps sync in an interactive terminal offers to migrate: it writes a branch file, syncs it, and offers to move your installs onto the branch. See Migrating from nuon apps sync.

Installs

Command	What it does
`nuon installs create`	Create an install of the selected app.
`nuon installs list`	List installs. Add `--labels k=v` (repeatable) to filter; all labels must match.
`nuon installs get`	Show an install’s details.
`nuon installs labels set --install-id <install> k=v ...`	Set labels on an install. Install group label selectors match on these.
`nuon installs labels list --install-id <install>`	List an install’s labels.
`nuon installs labels unset --install-id <install> <key> ...`	Remove labels from an install.
`nuon installs components deploy-all`	Deploy all components to an install.
`nuon installs outputs`	View an install’s outputs.

Operate

Command	What it does
`nuon runbooks --install-id <id>`	View and run runbooks for an install.
`nuon actions`	Manage and run app actions.
`nuon components`	Manage app components.

Agents / MCP

Operate Nuon from an LLM client. See Agents.

Command	What it does
`nuon agents help`	Setup guide. When an agent runs it, prints orientation markdown: auth, selected org/app/install, MCP HTTP URL, and the tool catalog.
`nuon agents mcp`	Stdio MCP proxy (`--allow-writes` in examples so mutating tools are listed). Its URL is derived from the configured API hostname (`api.<hostname>` becomes `mcp.<hostname>/mcp`). `--url` / `--name` override the upstream server and the name in the client’s MCP list. Per-client registration: Setup.

Help

Command	What it does
`nuon <command> --help`	Help for any command.
`nuon docs`	Open the docs.
`nuon completion <shell>`	Generate shell autocompletion.
`nuon version`	Show the installed CLI version.

Cloud Reference

Interface Reference

Architecture Reference

Global flags

Names and defaults

Authenticate

Organizations

Apps & config

App branches

Installs

Operate

Agents / MCP

Help

​Global flags

​Names and defaults

​Authenticate

​Organizations

​Apps & config

​App branches

​Installs

​Operate

​Agents / MCP

​Help

Global flags

Names and defaults

Authenticate

Organizations

Apps & config

App branches

Installs

Operate

Agents / MCP

Help