Workflow
CLI reference
Validate, build, deploy, and inspect your project from the terminal.
Install and sign in
Nubes is available at usenubes.com. Agents should start with the deployment guide, after checking that the current directory contains the intended application.
Install the native CLI on macOS or Linux:
curl --fail --silent --show-error --location https://usenubes.com/setup.sh -o /tmp/nubes-setup.sh
sh /tmp/nubes-setup.sh
export PATH="$HOME/.local/bin:$PATH"
export NUBES_API_URL='https://fast-greyhound-109.convex.site'
nubes loginThe installer supports amd64 and arm64 and verifies the archive’s SHA-256 checksum. It requires curl, tar with xz support, and sha256sum or shasum. Windows users can use WSL.
Login opens a WorkOS verification page. Sign in and confirm the displayed code in your browser. Agents should bring that page to the foreground and let you authenticate. Use nubes login --no-browser in a headless terminal. The CLI stores and refreshes your session; nubes logout removes the local session.
Service and CI workflows can provide NUBES_TOKEN, which takes precedence over a saved user session. Keep credentials out of source files and logs.
Local commands
With the nubes executable available on your PATH, run commands from your project directory. Commands default to nubes.hcl; pass a file path to use another location.
| Command | Behavior |
|---|---|
nubes validate [file.hcl] |
Check configuration without building or uploading files |
nubes fmt [file.hcl] |
Format the configuration in place |
nubes fmt --check [file.hcl] |
Report formatting problems without editing |
nubes plan [file.hcl] |
Summarize local resources and packaged files without deploying |
nubes build [file.hcl] |
Run configured static site builders and check output locally |
nubes build . |
Discover and build configurations below the current directory |
Validation, formatting, and planning make no network requests. Build commands run your site’s configured builder, which may itself access the network. Planning requires source files and any static site output to exist; it does not compare deployed state.
Deployment
nubes deploy nubes.hcl --project-id YOUR_PROJECT_ID --environment productionUse NUBES_API_URL, NUBES_TOKEN, and optionally NUBES_PROJECT_ID for deployment setup. --skip-build skips local static site builders when deploying existing output.
Inspect the API
List available operations, inspect the inputs of one operation, then call it:
nubes api
nubes api project.get --describe
nubes api project.get --data '{"projectId":"YOUR_PROJECT_ID"}' --jsonDiscovery and --describe work locally. API calls use the configured API URL, and authenticated operations use your WorkOS login or NUBES_TOKEN. Use --describe to check the required parameters and request body before calling an operation.
Automation and output
--json writes machine-readable results to standard output. --progress human|json|none controls progress messages on standard error; it defaults to human.
Use nubes --help or nubes COMMAND --help for the options available in your installed CLI. Keep tokens in your CI system’s secret settings, and make deployment a deliberate step after validation and review.
MCP and platform health
The remote MCP endpoint is https://fast-greyhound-109.convex.site/mcp and uses WorkOS OAuth. Discover its tools after signing in. Dashboard operations use the same organization and membership permissions as the dashboard.
nubes api system.platformHealth --json reports the current UTC day’s checks of Nubes platform services. Probes run every five minutes; missing or stale measurements are reported as unknown. The public HTTP endpoint is platform health.