CLI

NEXUS AI CLI Reference

The nexus CLI deploys and operates NEXUS AI resources from a terminal or CI system. This page documents CLI 4.1.8. Run nexus --help and nexus <command> --help for the exact syntax installed on your machine.

Installation

# macOS
curl -fsSL https://nexusai.run/install-mac.sh | bash

# Linux
curl -fsSL https://nexusai.run/install.sh | bash

# npm (Node.js 18+)
npm install -g nexusapp-cli@latest

nexus --version
nexus --help

Authentication and configuration

nexus auth login
nexus auth whoami
nexus auth logout

Browser login stores configuration in ~/.nexusai/config.json with restricted file permissions.

Environment variable	Purpose
`NEXUSAI_TOKEN`	Scoped access token; overrides the saved token
`NEXUSAI_API_URL`	API origin override; defaults to `https://nexusai.run`

For CI:

export NEXUSAI_TOKEN="nxk_..."
export NEXUSAI_API_URL="https://nexusai.run"
nexus auth whoami

Never print a token or commit it to source control.

Command map

nexus auth          Authentication
nexus deploy        Deployment lifecycle
nexus secret        Secrets Vault
nexus project       Projects
nexus builder       AI app generation, editing, checks, and deployment
nexus domain        Custom domains
nexus token         Access tokens
nexus member        Organization members
nexus db            Deployment database services and backups
nexus managed-db    Standalone local/cloud databases
nexus volume        Persistent filesystem volumes
nexus bucket        S3-compatible buckets and objects
nexus exec          Execute in a running docker deployment
nexus cp            Copy one file to/from a running docker deployment

Most read/list commands support --json for automation.

Terminal AI Builder

The CLI Builder uses the same session and checkpoints as the browser Builder. Like the browser, it creates a project behind the scenes after your first prompt. Configure an AI provider in your organization, then run:

nexus builder providers
nexus builder chat
# At builder>, describe the app you want.

# Or generate from a one-shot prompt:
nexus builder new "Build a task tracker with a dashboard"

# Resume a previous build:
nexus builder chat --project <project-id>

new and the first prompt in a fresh chat derive the project name from your description, as the browser does. Use --name to choose a name, or --provider and --model to select the AI provider and model. The CLI prints the project ID for resuming later. Inside chat, type /help (or help) for guidance, /provider and /model for numbered AI choices, /status for current settings, /new to start another app, or /exit to return to the main CLI prompt. /files, /check, /fix, and /preview are available there too. Provider/model changes apply to the next AI message. ask --project <id> "..." sends a one-shot follow-up; start --project <id> opens or creates that project's session. AI turns use the project's Builder quota.

Use Up/Down to revisit commands in the main CLI shell and prompts in Builder chat, including after you leave and re-enter chat in the same CLI session. History is in memory only and is cleared when the CLI process exits; it is not written to disk because commands may contain credentials.

Edit and sync files

# Live two-way sync: use any editor as your IDE while you chat with the AI.
nexus builder dev --project <project-id> --dir ./my-app --open
# One sync pass (scripts, CI, or occasional use):
nexus builder sync --project <project-id> --dir ./my-app

nexus builder files --project <project-id>
nexus builder pull --project <project-id> --out ./my-app
nexus builder push --project <project-id> --from ./my-app
nexus builder put src/App.tsx --from ./App.tsx --project <project-id>
nexus builder rm src/unused.ts --project <project-id>

dev downloads the app into an empty or new folder (or resumes a folder created by pull, sync, or dev), then keeps it in sync: saved edits become Builder checkpoints, AI changes from the dev> prompt or the browser are written into the folder, and edits on both sides are merged with a three-way line merge. Lines changed on both sides get git-style conflict markers (<<<<<<< local / ======= / >>>>>>> nexus); a file with markers is never uploaded and syncs once they are removed, while other edits keep syncing. Before each AI turn, pending local edits are saved first. At the dev> prompt: /open, /sync, /status, /check, /fix, /preview, /exit. --interval sets how often Builder is checked (default 4 seconds). sync runs one pass and exits with code 1 while conflicts are unresolved. Both keep the last synced snapshot in .nexus-builder.base.json next to .nexus-builder.json. If most files vanish at once, sync stops rather than deleting them in Builder; pass --allow-deletes to confirm.

pull requires an empty destination; it does not overwrite local edits. push uses the pull manifest and rejects a stale Builder checkpoint so browser changes cannot be overwritten silently (run sync on the folder to merge instead). Removed files require --delete; .git, node_modules, build output, and local .env files are excluded from directory sync. Individual put and rm commands also create checkpoints.

Check, fix, preview, and deploy

nexus builder check --project <project-id>
nexus builder fix --project <project-id> --attempts 2
nexus builder versions --project <project-id>
nexus builder revert <message-id> --project <project-id>
nexus builder open --project <project-id>
nexus builder deploy --project <project-id> --name my-app --provider docker
nexus deploy status my-app --watch

check validates JavaScript, TypeScript, JSX, TSX, CSS, JSON/JSONC configuration, YAML, HTML, XML/SVG, and relative imports locally. It does not run a full build, install packages, type-check the entire project, or execute generated code. fix sends the diagnostics to Builder and reruns the check. Visual preview remains in the browser (open prints its URL). deploy is explicit and submits the latest Builder files to the existing deployment API; it may incur deployment charges or hit plan quotas. Use --framework for imported projects with a different framework and --region to choose a region. This command creates a new deployment; use the normal deployment commands to monitor or manage it.

Deployment commands

List and inspect

nexus deploy list
nexus deploy list --status RUNNING
nexus deploy list --project <project-id>
nexus deploy get <name-or-id>
nexus deploy status <name-or-id>
nexus deploy status <name-or-id> --watch

Deployment names and IDs are accepted where the command says <name-or-id>. Use IDs in automation when names may be ambiguous.

Deploy an image

nexus deploy create \
  --image nginx:latest \
  --port 80 \
  --name web \
  --provider docker

Provider values:

docker
gcp_cloud_run
aws_ecs_fargate
azure_container_apps

Deploy source

nexus deploy source \
  --repo https://github.com/you/app.git \
  --name app \
  --branch main \
  --provider docker \
  --environment PRODUCTION \
  --wait

Important options:

Option	Purpose
`--project <id>`	Deploy into a specific project
`--region <region>`	Select the cloud region
`--env KEY=VALUE`	Add environment variables
`--env-file <file>`	Load dotenv-style variables
`--framework <name>`	Supply a framework hint
`--install-command <cmd>`	Override dependency installation
`--build-command <cmd>`	Override build
`--start-command <cmd>`	Override runtime start
`--output-dir <dir>`	Set build output directory
`--dockerfile <value>`	Repo path, local file, URL, or inline Dockerfile
`--repo-secret <name>`	Secret containing a private-repo token
`--auto-destroy <hours>`	Schedule cleanup for an ephemeral deploy
`--services <types>`	Comma-separated database/cache services
`--create-db <engine>`	Create one Postgres/MySQL database
`--managed-db <id>`	Attach an existing managed database
`--db-version`, `--db-region`	Managed database options
`--worker-command <cmd>`	Run a background worker sidecar
`--worker-name <name>`	Name the worker service
`--no-health-check`	Disable HTTP health checking intentionally
`--wait`	Wait for `RUNNING` or `FAILED`

Full-stack docker example:

nexus deploy source \
  --repo https://github.com/you/app.git \
  --name app \
  --provider docker \
  --services postgresql,redis \
  --worker-command "npm run worker" \
  --wait

Cloud app with managed Postgres:

nexus deploy source \
  --repo https://github.com/you/app.git \
  --name app \
  --provider gcp_cloud_run \
  --region us-central1 \
  --create-db postgres \
  --wait

Logs and health

nexus deploy logs app
nexus deploy logs app --type build --lines 200
nexus deploy logs app --follow
nexus deploy status app --watch

Redeploy and rollback

nexus deploy redeploy app --wait
nexus deploy rollback app
nexus deploy rollback app --target <deployment-id> --yes

Scale, stop, start, and delete

nexus deploy scale app 3
nexus deploy stop app
nexus deploy start app
nexus deploy delete app --yes

Replica range and provider support are validated by the API.

Auto-destroy

nexus deploy auto-destroy app --in 4h
nexus deploy auto-destroy app --at 2026-12-01T04:00:00Z
nexus deploy auto-destroy app --off

Changing auto-destroy does not restart the deployment.

Packaged deployments

The CLI includes guided commands for OpenClaw and Flixty:

nexus deploy openclaw --help
nexus deploy flixty --help

Review every generated secret and OAuth callback URL before using these in production.

Secrets

nexus secret list
nexus secret list --environment PRODUCTION
nexus secret create --name DATABASE_URL --environment PRODUCTION
nexus secret update <secret-id>
nexus secret delete <secret-id> --yes

Interactive entry is preferred. --value is available but can expose a value through shell history.

Projects

nexus project list
nexus project create --name "Production API"
nexus project delete <project-id> --yes

Use different project IDs for independently deployed environments of the same repository.

Custom domains

nexus domain list app
nexus domain add app api.example.com
nexus domain verify app <domain-id>
nexus domain remove app <domain-id>

Use the domain ID returned by list/add. Apply exactly the DNS records shown by the platform.

Access tokens

nexus token list
nexus token create
nexus token revoke <token-id>

Create the smallest scope set needed. The token value is sensitive and may only be displayed at creation.

Team members

nexus member list
nexus member invite developer@example.com --role MEMBER
nexus member role <user-id> MEMBER
nexus member suspend <user-id>
nexus member activate <user-id>

Role changes require organization permissions. CLI roles are ADMIN, MEMBER (shown as Developer), DEPLOYMENT_MANAGER, AUDITOR, and BILLING_MANAGER; ownership transfer is not performed by this command.

Deployment database services and backups

nexus db services
nexus db services app
nexus db backup <service-id>
nexus db backups <service-id>
nexus db backup-download <service-id> <backup-id> --out ./backup.dump
nexus db backup-upload <service-id> ./backup.dump
nexus db restore <service-id> <backup-id> --yes
nexus db restore-to <target-service-id> <backup-id> --yes
nexus db backup-delete <service-id> <backup-id> --yes

Daily backups:

nexus db backup-schedule <service-id> --enable --retention 7
nexus db backup-schedule <service-id> --disable

Restore in place is destructive. restore-to requires a compatible engine in the same organization.

Standalone managed databases

List and create

nexus managed-db list

# Local Postgres
nexus managed-db create app-db \
  --local \
  --engine postgres \
  --db-name appdb \
  --password-stdin

# Cloud managed database
nexus managed-db create app-db \
  --provider GCP_CLOUD_SQL \
  --engine postgres \
  --engine-version 17.10 \
  --region us-central1 \
  --instance-class db-custom-1-3840 \
  --allocated-gb 20

Cloud provider values are AWS_RDS, GCP_CLOUD_SQL, and AZURE_DATABASE. Supported engines and versions depend on provider.

Connect and attach

nexus managed-db connection app-db
nexus managed-db attach app-db --deployment <name-or-id>
nexus managed-db detach app-db --deployment <name-or-id>

Redeploy after changing an attachment.

Query and snapshots

nexus managed-db query app-db "SELECT now()"
nexus managed-db snapshot app-db
nexus managed-db snapshots app-db
nexus managed-db restore app-db \
  --snapshot <snapshot-id> \
  --new-name restored-app-db

Restore creates a new database. Delete is destructive:

nexus managed-db delete app-db
# Required only when the database is still attached:
nexus managed-db delete app-db --force

Volumes

nexus volume list
nexus volume create app-data --display-name "App data"
nexus volume attach <volume-id> <deployment-id> --mount /data
nexus deploy redeploy <deployment-id> --wait
nexus volume refresh-usage <volume-id>
nexus volume detach <volume-id>
nexus volume delete <volume-id> --yes

Volumes must be detached before deletion. Attach/detach takes effect after redeploy.

Buckets

nexus bucket list
nexus bucket create user-uploads --display-name "User uploads"
nexus bucket attach <bucket-id> <deployment-id>
nexus deploy redeploy <deployment-id> --wait
nexus bucket refresh-usage <bucket-id>
nexus bucket credentials <bucket-id>
nexus bucket rotate-credentials <bucket-id> --yes
nexus bucket detach <bucket-id> <deployment-id>
nexus bucket delete <bucket-id> --yes

Objects:

nexus bucket files <bucket-id> --prefix uploads/
nexus bucket upload <bucket-id> ./report.pdf --key reports/report.pdf
nexus bucket download <bucket-id> reports/report.pdf --out ./report.pdf
nexus bucket rm <bucket-id> reports/report.pdf --yes

Bucket deletion removes all objects and requires detachment first.

Execute and copy

Available only for running docker deployments:

nexus exec <deployment-id> -- ls -la /app
nexus cp ./index.html <deployment-id>:/app/public/index.html
nexus cp <deployment-id>:/app/config.json ./config.json

exec is non-interactive and output is capped. cp copies one file. Runtime edits do not survive image replacement.

CI/CD example

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g nexusapp-cli@latest
      - name: Deploy
        env:
          NEXUSAI_TOKEN: ${{ secrets.NEXUSAI_TOKEN }}
        run: |
          nexus deploy source \
            --repo "https://github.com/${{ github.repository }}.git" \
            --branch "${{ github.ref_name }}" \
            --name app-production \
            --environment PRODUCTION \
            --wait

Use a dedicated scoped token, pin versions when reproducibility matters, and avoid putting application secrets on the command line.

Exit codes and scripting

A successful command exits 0.
Validation, authentication, API, or failed wait operations exit non-zero.
Use --json where available instead of parsing tables.
Use --yes only after resolving the exact resource ID.

Troubleshooting

Not logged in

nexus auth login
# or
export NEXUSAI_TOKEN="nxk_..."

Wrong API origin

export NEXUSAI_API_URL="https://nexusai.run"

Deployment not found

nexus deploy list --json

Confirm organization, project, exact name, and ID.

Forbidden

Check organization role, access-token scopes, plan availability, and resource ownership.

App never becomes healthy

Check build/runtime logs, 0.0.0.0 binding, service port, startup duration, required secrets, and dependency connectivity.

CLI

NEXUS AI CLI Reference

Installation

Authentication and configuration

Command map

Terminal AI Builder

Edit and sync files

Check, fix, preview, and deploy

Deployment commands

List and inspect

Deploy an image

Deploy source

Logs and health

Redeploy and rollback

Scale, stop, start, and delete

Auto-destroy

Packaged deployments

Secrets

Projects

Custom domains

Access tokens

Team members

Deployment database services and backups

Standalone managed databases

List and create

Connect and attach

Query and snapshots

Volumes

Buckets

Execute and copy

CI/CD example

Exit codes and scripting

Troubleshooting

Not logged in

Wrong API origin

Deployment not found

Forbidden

App never becomes healthy

Related pages

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

NEXUS AI Wiki

Build and deploy

Data and security

Interfaces

Help

Clone this wiki locally