# NEXUS CLI App Builder

The NEXUS CLI App Builder builds and edits an AI-generated application from the terminal. It uses the same Builder project, files, and checkpoints as the browser AI App Builder. The CLI is a control surface for generation, file sync, static checks, and deployment; visual preview remains in the browser.

The [hands-on Knowledge Base guide](https://nexusai.run/kb/cli-app-builder) provides a full issue-tracker example and troubleshooting steps. This document is the concise command reference for agents and terminal workflows.

## Who should use it?

Use the CLI Builder when a developer wants to start an app from a prompt in the terminal, continue an existing Builder project, or combine AI edits with a local code editor. Use the browser Builder to interact with the preview or make visual changes. Use regular source deployment when the app is an independent repository rather than a Builder snapshot.

An agent should not infer that a passing static check proves production readiness. It should inspect changes, run the app's own build and tests when available, and ask for approval before deploying if deployment was not requested.

## How do I start a new app?

Install Node.js 18 or later and the CLI, then sign in:

```bash
npm install -g nexusapp-cli@latest
nexus auth login
nexus builder chat
```

At the `builder>` prompt, type an ordinary app description. The first prompt creates the NEXUS AI project automatically and prints its project ID. For example:

```text
builder> Build a small issue tracker with a list, status filter, issue detail view, and add-issue form. Use sample data and a mobile-friendly layout.
```

Save the printed ID. `nexus builder chat --project <id>` resumes that project later. `nexus builder new "Build a small issue tracker"` is a one-shot alternative. For a one-shot follow-up on an existing project, run `nexus builder ask --project <id> "Add an empty state to the filtered list"`.

## What can I do inside chat?

| Command | Effect |
| --- | --- |
| `/help` | List chat commands and common Builder CLI commands. |
| `/provider`, `/model` | Choose from providers and models available to the account. This changes subsequent AI turns. |
| `/status` | Show the current project, provider, model, and file count. |
| `/files` | List the current Builder files. |
| `/check` | Run static syntax and relative-import checks. |
| `/fix` | Ask AI to repair reported errors, then rerun checks. |
| `/preview` | Print the browser Builder URL. |
| `/new` | Start another app with the next ordinary prompt; the previous project remains. |
| `/exit` | Leave Builder chat. |

Up and Down revisit prompts and commands from the current CLI process; history is not persisted across restarts. Slash commands work at `builder>`, not in the normal shell. Run `nexus builder --help` in the normal shell for command flags.

`nexus builder providers` lists provider IDs. The selected AI provider generates code; `builder deploy --provider` names the infrastructure provider where the app runs. These are separate choices.

## How do I check and repair files?

```bash
nexus builder files --project <id>
nexus builder check --project <id>
nexus builder fix --project <id>
nexus builder check --project <id>
```

The check examines supported text files for syntax and verifies relative imports against the snapshot. It does not execute the app, typecheck the entire project, run its tests, or verify security. `fix` sends diagnostics to the AI and may consume Builder quota. Review its changes and test the preview after it reports success.

## How do I edit in a local editor?

```bash
nexus builder pull --project <id> --out ./issue-tracker
# Edit the downloaded text files in your editor.
nexus builder push --project <id> --from ./issue-tracker
nexus builder check --project <id>
```

Pull requires an empty destination and creates a `.nexus-builder.json` manifest. Push uses that manifest to reject stale changes if another chat or browser edit created a newer checkpoint. If push is stale, keep the local edits, pull into a different empty directory, merge, and push the newer copy. Removing a previously pulled file requires `--delete` on push. To add or replace one file, use `nexus builder put <path> --from <local-file> --project <id>`; to delete one, use `nexus builder rm <path> --project <id>`.

Builder sync supports UTF-8 text files, up to 200 files and 2 MB total. It skips `.git`, `node_modules`, build output, and `.env` files. Do not place secrets in Builder source files.

## How do I preview, restore, and deploy?

```bash
nexus builder versions --project <id>
nexus builder open --project <id>
nexus builder deploy --project <id> --name issue-tracker --provider docker
nexus deploy list --project <id>
```

`versions` lists checkpoint message IDs. `nexus builder revert <message-id> --project <id>` restores an earlier file state as a new checkpoint. `open` prints the browser Builder and preview URL; it does not render the app in the terminal.

Deploy submits the current Builder snapshot as a new deployment only when explicitly invoked. It does not first run `builder check`, the app's build, or its tests. `docker` is the NEXUS AI deployment provider; other deployment providers may be available to the account. If the project has no framework hint, the CLI defaults to `nextjs`; pass `--framework <framework>` when the generated app needs a different one. Deployment consumes normal infrastructure quota and may incur charges.

## Canonical resources

- [Full CLI Builder walkthrough](https://nexusai.run/kb/cli-app-builder)
- [Browser AI App Builder](/docs/builder.md)
- [General CLI reference](/docs/cli.md)
- [Deployment](/docs/deployment.md)