# NEXUS AI CLI

The `nexus` CLI runs NEXUS AI operations from a terminal or CI system. Install it with `npm install -g nexusapp-cli@latest` (Node.js 18 or later). Run `nexus <command> --help` for the exact syntax of the installed version.

## Authentication

```bash
nexus auth login                  # browser OAuth
nexus auth login --token nxk_...  # existing access token
nexus auth whoami
nexus auth logout
```

In CI, set `NEXUSAI_TOKEN` instead of logging in. `NEXUSAI_URL` overrides the API URL.

## Deployments

```bash
nexus deploy source --repo https://github.com/you/app --name my-app --provider docker --services postgres,redis --wait
nexus deploy create --image nginx:latest --port 80 --name web --provider gcp_cloud_run
nexus deploy list --status RUNNING
nexus deploy status my-app --watch
nexus deploy logs my-app --follow
nexus deploy redeploy my-app --yes
nexus deploy rollback my-app --yes
nexus deploy scale my-app 3
nexus deploy stop my-app
nexus deploy start my-app
nexus deploy auto-destroy my-app --in 4h
nexus deploy delete my-app --yes
```

Providers: `docker` (NEXUS AI managed, full stack), `gcp_cloud_run`, `aws_ecs_fargate` (AWS App Runner), `azure_container_apps`. Useful `deploy source` options: `--project`, `--environment`, `--branch`, `--env KEY=VALUE`, `--env-file`, `--dockerfile`, `--services`, `--create-db`, `--managed-db <id>`, `--worker-command`, `--auto-destroy <hours>`.

Run commands in and copy files to a `docker` deployment (these take the deployment ID, not the name):

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

## Managed databases

```bash
nexus managed-db create shop --local --engine postgres
nexus managed-db create prod-db --provider GCP_CLOUD_SQL --engine postgres --engine-version 17
nexus managed-db connection shop --url-only
nexus managed-db attach shop --deployment my-app
nexus managed-db snapshot shop --notes "before migration"
nexus managed-db restore shop --snapshot <snapshot-id> --new-name shop-restored
nexus managed-db query shop "SELECT id, email FROM users LIMIT 10"
```

Always quote SQL. One statement per call; `CREATE DATABASE`, `GRANT`, and similar statements are blocked. See [SQL safety rules](/docs/sql-safety.md).

## Deployment database backups

```bash
nexus db services my-app
nexus db backup <service-id>
nexus db backups <service-id>
nexus db restore <service-id> <backup-id> --yes
nexus db backup-download <service-id> <backup-id> --out ./backup.dump
nexus db backup-schedule <service-id> --enable --retention 14
```

## Storage

```bash
nexus bucket create user-uploads
nexus bucket attach <bucket-id> <deployment-id>
nexus bucket upload <bucket-id> ./logo.png --key images/logo.png
nexus bucket download <bucket-id> images/logo.png --share --ttl 300
nexus volume create app-data
nexus volume attach <volume-id> <deployment-id> --mount /data
```

Redeploy after attaching a bucket, volume, or database.

## Secrets, domains, projects, team, tokens

```bash
nexus secret create --name API_KEY --environment PRODUCTION
nexus domain add my-app app.example.com
nexus domain verify my-app <domain-id>
nexus project create --name my-project
nexus member invite dev@example.com --role MEMBER
nexus token create --name ci --scopes deployments:read,deployments:create --expires 90d
```

## Output

Most read commands accept `--json`. Destructive commands prompt unless `--yes` is passed. Agents should use `--json` and only pass `--yes` after the user approves.

## Related resources

- [Deployment](/docs/deployment.md)
- [Managed databases](/docs/managed-databases.md)
- [Access tokens](/docs/tokens.md)
- [Environments](/docs/environments.md)