NuPaaS DocsOverview
The NuPaaS CLI manages projects, deployments, databases, domains and nodes from your terminal. It talks to the same public REST API documented under API reference, so anything the CLI can do you can also automate directly over HTTP.
Install
The CLI is published to npm as @type-driven/platform-cli. Installing it globally puts a platform executable on yourPATH. The npm package is a thin launcher that selects the prebuilt binary matching your operating system and CPU architecture.
npm install -g @type-driven/platform-cliConfirm the install and check which version you are running:
platform --version
platform --helpEvery command and subcommand accepts --help. If this page and the CLI ever disagree, platform <command> --help is authoritative — it is generated from the command definitions themselves.
Configure
platform init is an interactive wizard that records the API endpoint, your credentials and a default organization. It writes ~/.platform/config.json with file mode 0600.
platform initPass every value up front to configure a machine without prompts — this is the form to use in CI images and provisioning scripts:
platform init --api-url https://platform.nupaas.com --api-key plat_REPLACE_ME --org my-org| Parameter | Type | Description |
|---|---|---|
| --api-url | string | Base URL of the platform. The CLI appends /api/v1 itself, so pass the host root. |
| --api-key | string | A long-lived API key. Create one with platform keys create. |
| --org | string | Default organization, used whenever a command's --org flag is omitted. |
The recorded default organization is what makes --org optional on later commands. Without it, commands that need an organization fail with a message telling you to pass --org or run platform init.
Authenticate
There are two ways to authenticate, and they suit different situations.
Interactive login
platform login runs a browser-based OIDC authorization code flow. It starts a temporary local callback server, opens your browser, exchanges the resulting code for tokens, and saves the access token into ~/.platform/config.json. If no terminal is attached it prints the URL for you to open manually instead.
platform login
platform login --org my-orgAPI keys for automation
Non-interactive environments should use an API key instead. Set PLATFORM_API_KEY in the environment and the CLI will use it without reading the config file at all.
export PLATFORM_API_URL=https://platform.nupaas.com
export PLATFORM_API_KEY=plat_REPLACE_ME
platform projects listCredentials are resolved in a fixed order: PLATFORM_API_KEY first, then the session token saved by platform login, then a long-lived key stored in the config file. The environment variable always wins, which is what lets a CI job override whatever a developer image happened to be logged in as. The API base URL resolves the same way: PLATFORM_API_URL first, then apiUrl from the config file. There is no built-in default — an unconfigured CLI fails with a clear message rather than guessing a host.
Command groups
Commands are grouped by the resource they act on. Each group is documented with its subcommands and flags on its own page or via --help.
| Parameter | Type | Description |
|---|---|---|
| platform deploy | group | List, create, wait on and roll back deployments. See the deploy page. |
| platform logs | command | Print or follow the build logs for one deployment. |
| platform projects | group | List, inspect, create and delete projects. |
| platform env | group | Read and write project environment variables and CI secrets. |
| platform db | group | Provision and inspect managed databases. See the database page. |
| platform node | group | Add, drain and remove fleet servers. See the servers page. |
| platform node-groups | group | Group servers and roll a component out across a group. |
| platform domains | group | Attach, verify and remove custom hostnames on a project. |
| platform keys | group | Create, list and revoke API keys. |
| platform orgs | group | Inspect organizations, list members and send invitations. |
| platform storage | group | Manage object storage buckets and inspect their usage. |
| platform stacks | group | Launch and inspect stacks created from a template. |
| platform billing | group | Read subscription status, invoices and usage. |
| platform audit | group | List and export the organization audit log. |
| platform local | group | Run and seed a local platform stack for development. |
Conventions
A handful of conventions hold across the whole CLI, so you only have to learn them once.
--jsonswitches a command from a human-readable table to raw JSON on stdout. Script against the JSON, never against the table.--orgis optional wherever it appears; it falls back to the default organization recorded byplatform init.- Tables print shortened identifiers for readability. Where a command takes an ID as a positional argument it will also accept one of those short prefixes and resolve it for you —
platform logsandplatform deploy waitboth do this. - Destructive commands prompt for confirmation before acting.
platform node removeaccepts--forceto skip the prompt in automation. - Commands exit non-zero on failure and print a single formatted error line, so
set -ein a shell script behaves as expected.
Operator-only commands
platform --help lists more groups than the ones above. Commands such as platform ops, platform bootstrap, platform grant-operator and platform golden-image operate on the platform fleet itself rather than on your organization's resources. They require a platform-operator grant, which is not something an organization role can confer on itself.
Running one of them without that grant returns a permission error. If you are a NuPaaS customer rather than a platform operator, the groups listed in the table above are the complete surface available to you.