The Complete NEXUS AI CLI Guide

By NEXUS AI Team · Contact: nexusai.run/contact

The complete NEXUS AI CLI guide: install, deploy from Git or images, databases, storage, domains, secrets, rollbacks, CI/CD, and 20 real use cases.

The nexus command line tool gives you the full NEXUS AI platform from a terminal: deploy apps from Git or a container image, add databases and storage, manage domains, secrets, and team access, and automate all of it in CI. This guide takes you from installation to production with real scenarios you can copy, adapt, and run.

If you want to build a new app with AI from the terminal, read the companion guide, NEXUS CLI App Builder. This guide covers everything else.

Who this guide is for

• Developers who want to ship an app without clicking through a dashboard.
• DevOps and platform engineers who need repeatable deploys, rollbacks, and backups.
• Teams automating releases from GitHub Actions or any other CI system.

Every example uses real commands and flags from the current CLI. Replace names such as my-app and shop with your own.

Install and sign in

The CLI needs Node.js 18 or later.

npm install -g nexusapp-cli@latest
nexus --version

On macOS or Linux you can also use the install script:

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

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

Sign in with your browser:

nexus auth login
nexus auth whoami

login opens a browser window, and the CLI saves your session in ~/.nexusai/config.json. whoami confirms which user and organization every later command acts on. Run it first whenever something looks wrong: most "not found" errors come from being signed in to a different organization.

To sign out and revoke the saved token:

nexus auth logout

Two ways to use the CLI

• Single commands. Run nexus deploy list, nexus deploy logs my-app, and so on from your normal shell.
• Interactive shell. Run nexus on its own to open the NEXUS AI prompt, then type commands without the nexus prefix. The Up and Down arrow keys recall earlier commands in the same session. History stays in memory and is never written to disk, because commands can contain credentials.

Get help at any level

nexus --help
nexus deploy --help
nexus deploy source --help

The built-in help always matches the version you have installed, so check it first when a flag in this guide does not work.

How NEXUS AI resources fit together

Knowing the building blocks makes every command easier to read.

Where your app runs

Choose the target with --provider:

Cloud providers use the credentials your organization configured in NEXUS AI. If a cloud deploy fails with a credentials error, check the provider settings in the dashboard first.

Names or IDs

Most commands accept a deployment name or ID, shown as <name-or-id> in help. A few commands (exec, cp, volume attach, bucket attach) need the deployment ID. Get IDs from:

nexus deploy list

In scripts, always use IDs. Two deployments can share a display name, but an ID is unique.

Use case 1: Ship your first app from GitHub

Scenario: you have a Node.js API in a public GitHub repository and want it live with a URL in a few minutes.

nexus deploy source \
  --repo https://github.com/acme/orders-api \
  --name orders-api \
  --provider docker \
  --wait

What happens:

1. NEXUS AI clones the repository and detects the framework. No Dockerfile is required.
2. It builds and starts the app, then runs health checks.
3. --wait keeps the terminal attached until the deployment is RUNNING or FAILED, then prints the URL.

Check it:

nexus deploy status orders-api
nexus deploy logs orders-api --lines 50

Your app must listen on 0.0.0.0, not localhost or 127.0.0.1, and on the port it declares (for example with EXPOSE in a Dockerfile). This is the most common reason a first deploy never becomes healthy.

Tune the build when detection is not enough

nexus deploy source \
  --repo https://github.com/acme/orders-api \
  --name orders-api \
  --provider docker \
  --branch release \
  --framework node \
  --install-command "npm ci" \
  --build-command "npm run build" \
  --start-command "node dist/server.js" \
  --wait

When the repository has a Dockerfile at its root, NEXUS AI uses it automatically and ignores the build and start commands.

Use case 2: Deploy a monorepo frontend and backend

Scenario: your repository has apps/web (a Vite frontend) and apps/api (an Express API). Deploy each folder as its own deployment so they scale and restart independently.

nexus deploy source \
  --repo https://github.com/acme/shop \
  --root-dir apps/api \
  --name shop-api \
  --provider docker \
  --wait

nexus deploy source \
  --repo https://github.com/acme/shop \
  --root-dir apps/web \
  --name shop-web \
  --provider docker \
  --env VITE_API_URL=https://shop-api.example.com \
  --wait

Frontend build variables such as VITE_API_URL are baked in at build time, so set them on the deploy (or redeploy) that builds the frontend.

Use case 3: Deploy a private repository

Scenario: the repository is private. Store a Git access token in the Secrets Vault once, then reference it by name.

# Prompts for the value, so the token never lands in shell history
nexus secret create --name GITHUB_TOKEN --environment PRODUCTION

nexus deploy source \
  --repo https://github.com/acme/billing-service \
  --repo-secret GITHUB_TOKEN \
  --name billing \
  --provider docker \
  --wait

Use a token with read-only access to the repository contents. If you connected the NEXUS AI GitHub App to your organization, repositories it can access are cloned without --repo-secret.

Use case 4: Deploy a ready-made container image

Scenario: your CI already builds and pushes an image, or you want to run an off-the-shelf image.

nexus deploy create \
  --image ghcr.io/acme/worker:1.4.2 \
  --port 8080 \
  --name acme-worker \
  --provider gcp_cloud_run \
  --env-file .env.production \
  --wait

--image and --port are required. Pin an exact tag such as 1.4.2 instead of latest so a redeploy never picks up an image you did not test.

Use case 5: Configure environment variables safely

Pass variables with --env (repeatable) or load a whole file with --env-file:

nexus deploy source \
  --repo https://github.com/acme/orders-api \
  --name orders-api \
  --provider docker \
  --env-file .env.production \
  --env NODE_ENV=production \
  --env LOG_LEVEL=info \
  --wait

The file uses standard dotenv format:

# Comments and blank lines are ignored
NODE_ENV=production
PAYMENTS_API_URL=https://api.payments.example.com
GREETING="value with spaces"

Rules to remember:

• --env wins over --env-file when both set the same key.
• On redeploy, your existing variables are kept. Only the keys you pass are added or changed.
• Keep .env.production out of Git. Add it to .gitignore.

Change one value on a running app:

nexus deploy redeploy orders-api --env LOG_LEVEL=debug --yes --wait

Use the Secrets Vault

The Secrets Vault stores values encrypted at rest (AES-256-GCM), scoped to an environment:

nexus secret create --name STRIPE_KEY --environment PRODUCTION     # prompts for the value
nexus secret list --environment PRODUCTION
nexus secret update <secret-id>                                    # prompts for the new value
nexus secret delete <secret-id> --yes

--value exists on create and update, but it leaves the value in your shell history. Prefer the prompt. From the CLI, a Vault secret is used directly by --repo-secret for private repositories. Values your app reads at runtime are passed with --env or --env-file.

Use case 6: Full-stack app with a database and a background worker

Scenario: a Django or Node app needs PostgreSQL, Redis for queues, and a worker process that consumes jobs.

On docker, services run as sidecars next to your app:

nexus deploy source \
  --repo https://github.com/acme/helpdesk \
  --name helpdesk \
  --provider docker \
  --services postgres,redis \
  --worker-command "npm run worker" \
  --wait

NEXUS AI starts PostgreSQL and Redis, injects their connection variables (such as DATABASE_URL) into the app, and runs npm run worker as a separate process from the same build. Rename the worker with --worker-name.

On a cloud provider, a database in --services is created as a managed cloud database instead. --create-db is a shortcut for exactly one database:

nexus deploy source \
  --repo https://github.com/acme/helpdesk \
  --name helpdesk \
  --provider gcp_cloud_run \
  --region us-central1 \
  --create-db postgres \
  --db-version 17 \
  --wait

Cloud databases take several minutes to provision. --wait covers that time.

Back up the database that runs with your app

Databases added with --services are deployment services. Manage their backups with nexus db:

nexus db services helpdesk                 # find the service ID
nexus db backup <service-id>               # take a backup now
nexus db backups <service-id>              # list backups
nexus db backup-schedule <service-id> --enable --retention 14   # daily, keep 14 days

Retention defaults to 7 days and cannot go lower.

Use case 7: A standalone database shared by several apps

Scenario: your API and your admin dashboard read the same PostgreSQL database. Create it once, independently of any app, and attach it to both. Standalone databases are available on paid plans.

# Run it on NEXUS AI
nexus managed-db create shop --local --engine postgres --db-name shop_db

# Attach it to two apps, then redeploy each so they receive the variables
nexus managed-db attach shop --deployment shop-api
nexus managed-db attach shop --deployment shop-admin
nexus deploy redeploy shop-api --yes --wait
nexus deploy redeploy shop-admin --yes --wait

Attaching injects DATABASE_URL, DATABASE_HOST, DATABASE_PORT, DATABASE_USER, and DATABASE_PASSWORD on the next deploy. For Redis the prefix is REDIS. If an app already uses DATABASE_URL for something else, pick another prefix:

nexus managed-db attach shop --deployment shop-admin --env-prefix SHOP_DB

Keep a chosen password out of shell history:

echo "$SHOP_DB_PASSWORD" | nexus managed-db create shop --local --engine postgres --password-stdin

When you omit a password, one is generated for you.

Run it in your cloud instead

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

Providers are AWS_RDS, GCP_CLOUD_SQL, and AZURE_DATABASE. Instance classes follow each provider's naming, for example db.t3.micro on AWS. Cloud databases support postgres and mysql, and --engine-version is required. Supported versions depend on the provider, so check the provider console if a version is rejected.

Connect with your own tools

nexus managed-db connection shop              # host, port, user, password, URL
psql "$(nexus managed-db connection shop --url-only)"

Run SQL without installing a client

nexus managed-db query shop "SELECT id, email FROM users ORDER BY created_at DESC LIMIT 10"
nexus managed-db query shop "CREATE INDEX idx_orders_user ON orders (user_id)"
nexus managed-db query shop "SELECT count(*) FROM orders" --json

• Wrap the SQL in quotes so your shell passes it as one argument.
• PostgreSQL and MySQL only, one statement per call.
• UPDATE and DELETE need a WHERE clause.
• CREATE DATABASE, DROP DATABASE, GRANT, REVOKE, CREATE ROLE, and CREATE EXTENSION are blocked. For those, connect directly with psql or mysql.

Use case 8: Run a database migration safely

Scenario: you are about to ship a release that alters a large table. Take a snapshot first so you can recover in minutes if the migration goes wrong.

# 1. Snapshot before touching anything
nexus managed-db snapshot shop --notes "before orders.status migration"
nexus managed-db snapshots shop

# 2. Run the migration inside the running app container (docker provider)
nexus deploy list                                   # copy the deployment ID
nexus exec <deployment-id> --timeout 600 --workdir /app -- npm run migrate

# 3. Verify
nexus managed-db query shop "SELECT status, count(*) FROM orders GROUP BY status"

If something is wrong, restore the snapshot into a new database, check it, then point the app at it:

nexus managed-db restore shop --snapshot <snapshot-id> --new-name shop-restored
nexus managed-db detach shop --deployment shop-api
nexus managed-db attach shop-restored --deployment shop-api
nexus deploy redeploy shop-api --yes --wait

Restoring never overwrites the original database, so you can compare both before you switch.

For a database added with --services, the equivalent is nexus db backup before the migration and nexus db restore <service-id> <backup-id> to roll back. That restore replaces the current data in place, so take a fresh backup first if you might need the current state.

Use case 9: Debug a deployment that will not start

Scenario: the deploy finished with FAILED, or it is running but the URL returns errors. Work from the outside in.

# 1. What state is it in?
nexus deploy status orders-api

# 2. Did the build succeed?
nexus deploy logs orders-api --type build --lines 200

# 3. What does the app print at runtime?
nexus deploy logs orders-api --lines 200
nexus deploy logs orders-api --follow          # stream new lines, Ctrl+C to stop

# 4. Look inside the running container (docker provider)
nexus exec <deployment-id> -- env
nexus exec <deployment-id> -- ls -la /app
nexus exec <deployment-id> -- cat /app/package.json

Common causes and fixes:

When a command contains flags of its own (such as ls -la), put -- after the deployment ID so the CLI passes them to the container instead of reading them itself. exec is non-interactive, times out after 60 seconds by default (--timeout up to 1800), and caps output at 2 MB per stream.

Use case 10: Hotfix a file, then make it permanent

Scenario: a typo in a static page is live and you need it fixed now, on a docker deployment.

nexus cp <deployment-id>:/app/public/index.html ./index.html     # download
# edit ./index.html
nexus cp ./index.html <deployment-id>:/app/public/index.html     # upload

cp copies one file per call. Changes made this way are lost the next time the image is replaced by a redeploy, so commit the same fix to Git and redeploy afterward.

Use case 11: Release, watch, and roll back

Scenario: you merged a change, redeployed, and error rates went up.

# Ship the latest commit
nexus deploy redeploy orders-api --yes --wait

# Watch it live (refreshes every 3 seconds)
nexus deploy status orders-api --watch

# Something is wrong: go back to the previous version
nexus deploy rollback orders-api --yes
nexus deploy status orders-api --watch

redeploy rebuilds the same deployment in place, so attached databases, volumes, and buckets stay connected. rollback returns to the previous container image. To roll back to a specific earlier version, pass its deployment ID with --target <deployment-id>.

Use case 12: Handle a traffic spike, then save money overnight

nexus deploy scale orders-api 4       # between 1 and 10 replicas
nexus deploy scale orders-api 1       # back to normal

nexus deploy stop staging-api         # pause a non-production app
nexus deploy start staging-api        # bring it back in the morning

Replica limits also depend on your plan and provider, and the API tells you when a value is not allowed. stop keeps the deployment, its configuration, and its data. Use delete only when you want it gone for good.

Use case 13: Preview environments that clean up after themselves

Scenario: each pull request gets its own temporary deployment for review, and nobody has to remember to delete it.

nexus deploy source \
  --repo https://github.com/acme/orders-api \
  --branch feature/refunds \
  --name orders-api-pr-218 \
  --provider docker \
  --auto-destroy 48 \
  --wait

--auto-destroy 48 deletes the deployment 48 hours after creation. Change the timer on an existing deployment without restarting it:

nexus deploy auto-destroy orders-api-pr-218 --in 4h                      # 30m, 4h, 2d
nexus deploy auto-destroy orders-api-pr-218 --at 2026-10-01T18:00:00Z
nexus deploy auto-destroy orders-api-pr-218 --off                        # keep it

Use case 14: Keep dev, staging, and production apart

Use one project per environment so the same repository can run three times without collisions:

nexus project create --name "Orders Dev"
nexus project create --name "Orders Staging"
nexus project create --name "Orders Production"
nexus project list                    # copy the three IDs

nexus deploy source \
  --repo https://github.com/acme/orders-api \
  --branch main \
  --project <production-project-id> \
  --environment PRODUCTION \
  --name orders-api \
  --provider aws_ecs_fargate \
  --env-file .env.production \
  --wait

--environment accepts DEVELOPMENT (the default), STAGING, and PRODUCTION. Filter by project later:

nexus deploy list --project <production-project-id>

Use case 15: Put the app on your own domain

nexus domain add orders-api api.acme.com

Create the DNS record the command prints (usually a CNAME pointing at the deployment URL) at your DNS provider, then verify:

nexus domain list orders-api                      # shows the domain ID and status
nexus domain verify orders-api <domain-id>

DNS changes can take from a few minutes to a few hours to propagate. Run verify again until it succeeds. If you use Cloudflare, start with the record set to DNS only (grey cloud) until the domain is verified. Custom domains are available on Starter plans and above. Remove a domain with nexus domain remove orders-api <domain-id> --yes.

Use case 16: Store user uploads and persistent files

Object storage with a bucket

Scenario: your app stores avatars and invoices.

nexus bucket create user-uploads
nexus bucket list                                     # copy the bucket ID
nexus bucket attach <bucket-id> <deployment-id>
nexus deploy redeploy <deployment-id> --yes --wait

After the redeploy, the app receives S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY, and S3_SECRET_KEY. Point any S3 SDK (AWS SDK, boto3) at S3_ENDPOINT and it works without code changes.

Manage files from the terminal:

nexus bucket upload <bucket-id> ./logo.png --key brand/logo.png
nexus bucket files <bucket-id> --prefix brand/
nexus bucket download <bucket-id> brand/logo.png --out ./logo.png
nexus bucket download <bucket-id> invoices/1042.pdf --share --ttl 600   # signed link, 10 minutes
nexus bucket rm <bucket-id> brand/old-logo.png --yes

Each bucket has its own scoped credentials. Revealing them is audit-logged, and you can rotate them if they leak:

nexus bucket credentials <bucket-id>
nexus bucket rotate-credentials <bucket-id> --yes
nexus deploy redeploy <deployment-id> --yes --wait     # apps pick up the new keys

A persistent disk with a volume

Scenario: a self-hosted CMS writes to /data and must keep its files across redeploys. Volumes work with docker deployments.

nexus volume create cms-data
nexus volume list                                      # copy the volume ID
nexus volume attach <volume-id> <deployment-id> --mount /data
nexus deploy redeploy <deployment-id> --yes --wait

Without --mount, the volume mounts at /data. Volumes survive restarts, redeploys, and host reboots. Detach a volume before deleting it.

Use case 17: Automate deploys from GitHub Actions

Step 1: create a scoped token. Give CI only the permissions it needs, with an expiry.

nexus token create \
  --name github-actions-orders \
  --scopes deployments:read,deployments:create,deployments:logs \
  --expires 90d

The token value is shown once. Copy it into your repository secrets as NEXUSAI_TOKEN.

Step 2: add the workflow at .github/workflows/deploy.yml:

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g nexusapp-cli@latest
      - name: Redeploy
        env:
          NEXUSAI_TOKEN: ${{ secrets.NEXUSAI_TOKEN }}
        run: nexus deploy redeploy ${{ secrets.NEXUSAI_DEPLOYMENT_ID }} --yes --wait

Store the deployment ID as NEXUSAI_DEPLOYMENT_ID. With --wait, the job fails when the deployment ends in FAILED, so a broken release turns your pipeline red instead of passing silently.

Useful scopes:

Review and clean up tokens regularly:

nexus token list --show-last-used
nexus token list --unused-since 30          # candidates for removal
nexus token revoke <token-id> --yes

Any command reads NEXUSAI_TOKEN from the environment, so no nexus auth login is needed in CI.

Use case 18: Script the CLI with JSON output

Most list and inspect commands accept --json. Parse that instead of the printed tables, which can change between versions.

# Names of all failed deployments
nexus deploy list --json | jq -r '.[] | select(.status == "FAILED") | .name'

# ID of one deployment by name
nexus deploy get orders-api --json | jq -r '.id'

# Nightly backup of every deployment database service
for id in $(nexus db services --json | jq -r '.[].id'); do
  nexus db backup "$id"
done

Exit codes are script-friendly: 0 means success, anything else means the command failed. --yes skips confirmation prompts, so only use it once your script has resolved the exact resource ID.

Use case 19: Onboard and offboard teammates

nexus member invite [email protected] --role DEPLOYMENT_MANAGER
nexus member list                               # shows user IDs and roles
nexus member role <user-id> AUDITOR             # change a role
nexus member suspend <user-id> --yes            # immediate offboarding
nexus member activate <user-id>                 # restore access

When someone leaves, suspend their account and revoke any tokens they created with nexus token revoke.

Use case 20: Move data between environments

Scenario: you want staging to start from a copy of production data (after removing anything sensitive).

# Production database service: take and download a backup
nexus db backup <prod-service-id>
nexus db backups <prod-service-id>                             # copy the backup ID
nexus db backup-download <prod-service-id> <backup-id> --out ./prod.dump

# Staging: upload it, then restore
nexus db backup-upload <staging-service-id> ./prod.dump
nexus db backups <staging-service-id>                          # copy the uploaded backup ID
nexus db restore <staging-service-id> <backup-id> --yes

Inside one organization you can also restore straight into another service of the same engine, without downloading:

nexus db restore-to <staging-service-id> <backup-id> --yes

To hand a backup to a teammate without sharing your credentials, create a signed link that expires (30 to 3600 seconds):

nexus db backup-download <service-id> <backup-id> --share --ttl 900

Quick reference

nexus auth        login | logout | whoami
nexus deploy      list | get | status | logs | source | create | redeploy | rollback
                  scale | stop | start | delete | auto-destroy | openclaw | flixty
nexus exec        <deployment-id> -- <command>
nexus cp          <local> <deployment-id>:<path>   or   <deployment-id>:<path> <local>
nexus secret      list | create | update | delete
nexus project     list | create | delete
nexus domain      list | add | verify | remove
nexus managed-db  list | create | connection | attach | detach | query
                  snapshot | snapshots | restore | delete
nexus db          services | backup | backups | backup-download | backup-upload
                  restore | restore-to | backup-delete | backup-schedule
nexus bucket      list | create | attach | detach | files | upload | download | rm
                  credentials | rotate-credentials | refresh-usage | delete
nexus volume      list | create | attach | detach | refresh-usage | delete
nexus token       list | create | revoke
nexus member      list | invite | role | suspend | activate
nexus builder     AI App Builder (see the CLI App Builder guide)

Flags you will use most

Environment variables

Troubleshooting

"Not logged in" or 401 errors. Run nexus auth login, or check that NEXUSAI_TOKEN is set and not expired or revoked.

403 Forbidden. Your role, your token's scopes, or your plan does not allow the action. Check nexus auth whoami, then the token scopes with nexus token list.

"Deployment not found". You may be in a different organization, or the name differs from what you typed. Run nexus deploy list --json and use the exact ID.

The deploy never reaches RUNNING. Read the build logs with --type build, confirm the app listens on 0.0.0.0 and the right port, and check that every required variable is set. See Use case 9 above.

Database or bucket variables are missing in the app. Attaching takes effect on the next deploy. Run nexus deploy redeploy <app> --yes --wait.

exec or cp fails. Both work only on running docker deployments and take the deployment ID, not the name. Add -- before any command that has its own flags.

A query is blocked. managed-db query refuses statements that change databases, roles, grants, or extensions. Use nexus managed-db connection and a native client for those.

A flag from this guide is rejected. Update the CLI with npm install -g nexusapp-cli@latest, then check nexus <command> --help.

Frequently asked questions

Is the CLI free? Yes. The CLI is free to install. What you deploy follows your NEXUS AI plan and quotas, and databases, cloud providers, and custom domains depend on your plan.

Can I use the CLI and the dashboard together? Yes. Both use the same API and the same data, so a deployment created in the terminal appears in the dashboard immediately, and the other way round.

Do I need a Dockerfile? No. NEXUS AI detects common frameworks (Node.js, Next.js, Vite, React, Vue, Python, PHP, Ruby, static sites) and builds them for you. If your repository has a Dockerfile, it is used.

Which cloud should I pick? Start with docker to get running fastest and to use exec, cp, and volumes. Use aws_ecs_fargate, gcp_cloud_run, or azure_container_apps when the app must run inside your own cloud account.

How do I update the CLI? Run npm install -g nexusapp-cli@latest, then nexus --version.

Can an AI assistant run these commands for me? Yes. NEXUS AI also offers an MCP server, so assistants such as Claude can deploy, read logs, and manage databases with the same permissions as your account.

Related guides

• NEXUS CLI App Builder: build and edit apps with AI from the terminal.
• Add a Deploy to NEXUS AI Button to Your GitHub Repo: let anyone deploy your repository in a few clicks.
• Documentation: full product documentation.

Start for free · Read the documentation · About NEXUS AI · Contact