Platform management
SDK-managed projects deploy to a platform you choose. Join one with void connect. Connections are stored per API origin, and credentials only work for that origin.
On this pageConnect to and switch between platforms · Find the operator commands · Understand previews and confirmation
Connection commands
Requires: platform admin login
These commands need an admin session from void platform auth login. Automation uses VOID_OPERATOR_TOKEN from a secret store. Never put it in project files.
Now you will run void platform list and void platform use.
void platform list
void platform use [id]Example output: the requested record, list, or a confirmation. Commands with --plan show the change without applying it.
Next, run void platform status.
void platform status [id]Example output: the requested record, list, or a confirmation. Commands with --plan show the change without applying it.
list shows the selected platform first, then the other saved platforms. If a platform has local installation records, its installation slug appears next to its name, such as Cloudflare Void (cloudflare). Select it with void platform use cloudflare. If a connected platform has no local slug, use its printed API URL.
use and status accept an installation slug, display name, saved ID or API URL. If a slug or name matches several platforms, use the API URL. With one platform, it is selected for you. With several, you get a picker. Non-interactive runs must name one. A project with a recorded platform URL keeps that platform when the global default changes.
For a self-hosted installation, status <installation-id> prints the locally saved progress, then checks the live API. The saved checkpoint may be out of date. If the live check fails during maintenance, the command still shows the checkpoint and exits with an error. It does not confirm that the platform is up.
Operator commands
Use void platform to manage users and apps on the selected platform. Start with the Platform Administration guide. It covers signing in, giving people access and investigating deploys.
Every command below accepts --connection <slug-or-url> to pick a registered platform, and --json for structured output. Display names and saved IDs also work. Without --connection, the CLI uses VOID_API_URL if set, then the active connection. App project files do not change this choice.
Making Changes
Commands that change users, projects, signup access, invitations or Workers show a preview, then ask you to confirm. This step previews a plan change, then applies it. Use the user ID from void platform user list.
void platform user plan <user-id> pro --plan
void platform user plan <user-id> pro --yesExample output: the requested record, list, or a confirmation. Commands with --plan show the change without applying it.
--plan checks the change and prints its effect without applying it. --yes applies it without a prompt. Scripts need --yes. Use one flag or the other, never both. These flags also apply to deploy cancellation and maintenance commands. They do not apply to auth commands.
Each preview and apply request has five minutes. Set --timeout <seconds> to a whole number from 1 to 3600 to change this. Read requests and single log polls have 30 seconds.
The SDK never retries changes on its own. If a request drops or times out, check the affected objects and void platform system events before you repeat it. Partial results list the work that finished and exit with a nonzero status.
Authentication
These commands sign you in, show your session or sign you out.
Now you will manage your platform admin session.
void platform auth login [--provider <connection-id>] [--token-stdin]
void platform auth statusExample output: the CLI prints your session state or confirms the change.
Next, manage your platform admin session.
void platform auth logout
void platform auth token [--token-stdin]Example output: the CLI prints your session state or confirms the change.
Browser login offers the platform's enabled methods. --provider <connection-id> picks one. Login saves a one-hour admin session in your system keychain. Logout revokes the session and removes the local credential.
auth token prints your current operator token. Treat the output as a secret. With --token-stdin, it reads a full admin API session from stdin and exchanges it for a new operator token. auth login --token-stdin saves the new token to the keychain instead of printing it.
For automation, pass VOID_OPERATOR_TOKEN from your secret store with an explicit VOID_API_URL or --connection. Operator tokens are stored apart from app deploy credentials. The API checks your admin access on every request. See Using Scripts for an example.
Pagination and JSON
User, project, deploy, invitation and event lists start at page 1 with 20 items. --limit takes 1 to 100. JSON responses include the page, limit and total count.
With --json, results go to stdout and errors go to stderr, both as JSON. Errors and partial failures exit nonzero. An unhealthy system health result stays on stdout and also exits nonzero. Following logs writes one JSON object per response, including empty ones.
Platform command groups
- Installation and maintenance
- Plans and authentication configuration
- Users, projects, and signup access
- Project Zero Trust
- Deployments, builds, and system operations
- Email administration
