NEXUS CLI App Builder

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

A hands-on guide to the NEXUS AI CLI Builder: start an app from a prompt, choose a model, edit files, fix errors, preview, and deploy.

The NEXUS CLI Builder is the terminal interface to the same AI App Builder used on the NEXUS AI website. You describe an app, the Builder creates files in a project, and later prompts revise that project. You can inspect and edit the files locally, check common syntax and import errors, open the browser preview, and explicitly deploy a snapshot. It is not a separate code generator: the terminal and browser use the same Builder session and checkpoints.

This guide follows one app from first prompt to deployment, then covers the commands you need when you want more control.

Who is it for, and when should you use it?

Use the NEXUS CLI Builder if you prefer a terminal workflow, want to make a quick app without first creating a project in the website, or want to combine AI changes with edits in your own code editor. It is also useful when you need a repeatable sequence of commands for an existing Builder project. A terminal beginner can stay in nexus builder chat; developers can pull the files, edit them locally, and push the result.

Use the browser Builder when you need to see and interact with the preview, use its visual editing tools, or inspect the app alongside the conversation. The NEXUS CLI prints a link to that page; it does not render a visual preview inside the terminal. If you already have an independent Git repository rather than a Builder snapshot, the regular source deployment workflow may be a better fit than starting a new Builder app.

The NEXUS CLI Builder does not silently deploy each AI response. Generation, checks, preview, and deployment are separate steps so you can inspect the result first.

Before you start

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

npm install -g nexusapp-cli@latest
nexus auth login
nexus auth whoami

nexus auth login opens a browser for sign-in. If you already use a NEXUS AI API token in a noninteractive environment, set NEXUSAI_TOKEN instead. Run nexus --help or nexus builder --help to confirm the commands supported by your installed version.

Your account also needs an available AI provider. To see the provider IDs and whether they are allowed for your account, run:

nexus builder providers

In interactive chat, /provider and /model present numbered choices, so you do not need to memorize IDs. If no provider is available, add or enable one under AI Providers on NEXUS AI Dashbaord. AI requests and automated fixes may use your Builder quota.

Example: build a small issue tracker

Start a new interactive build from your normal terminal:

nexus builder chat

The builder> prompt is inside the chat. Type a description of the app, not a shell command. Your first app prompt creates a NEXUS AI project automatically; you do not need to create one in the UI. For example:

builder> Build an issue tracker for a small team. Include an issue list, status and priority filters, an issue detail view, and a form to add an issue. Use realistic sample data. Keep the layout usable on a phone.

The CLI prints New build: ... (<project-id>), streams file and tool activity, and reports a saved checkpoint. Keep the project ID. It is the address you use to resume the app and run non-chat Builder commands. The app name and exact files depend on the generated result; this prompt is a concrete starting specification, not a guarantee that every requested behavior is production-ready.

To revise the same app, keep talking at builder>:

builder> Make the issue form validate the title and show an inline error instead of submitting an empty issue.
builder> Add an empty-state message when the selected filters match no issues.
builder> /files
builder> /check

Describe the change you want and its expected behavior. A focused follow-up is easier to inspect than asking for many unrelated features at once. /files lists the current snapshot. /check reports static diagnostics such as a file and line number; it does not run the app.

Type /help at any point for the chat commands. Use Up and Down to revisit earlier prompts and commands in the current CLI session. The history is held in memory and is not saved across restarts.

Choose an AI provider or model

You can choose before the first prompt, or switch while working on an app:

builder> /provider
Choose an AI provider:
  1. Claude ...
  2. OpenAI ...
Provider number (Enter to cancel): 1
builder> /model
builder> /status

The numbered entries reflect providers and models actually available to your account; they may differ from this example. The selection affects subsequent AI messages. Switching providers resets the model to that provider's default until you select another model. /status shows the current project, provider, model, and file count.

Here “AI provider” means the model service generating code. Later, builder deploy --provider ... means the infrastructure provider running the deployed app. They are different settings.

Start another app or resume this one

Inside chat, /new clears the current chat target; your next ordinary prompt creates another project. It does not delete the previous app. /exit leaves Builder chat. If you launched chat from the interactive nexus shell, you return to that shell; otherwise you return to your normal terminal.

To return to the issue tracker after leaving, run this in your normal terminal, replacing the placeholder with the ID printed when you created it:

nexus builder chat --project <project-id>

For a single prompt without entering chat, use:

nexus builder new "Build a responsive issue tracker with a list, filters, and an add-issue form"

That also creates a project automatically and prints its ID. For an existing project, a one-shot follow-up is:

nexus builder ask --project <project-id> "Add an empty state to the filtered issue list"

Inspect the files and fix a failed check

Outside chat, the equivalent commands are:

nexus builder files --project <project-id>
nexus builder check --project <project-id>

check examines supported text files for syntax errors and checks relative imports against the current Builder files. For example, an error might point to an import in src/App.tsx whose target file does not exist. If the reported issue is appropriate for AI repair, run:

nexus builder fix --project <project-id>
nexus builder check --project <project-id>

fix passes the diagnostics to the AI, saves its changes, and checks again. It attempts repair up to twice by default; --attempts 3 changes that limit (maximum 5). Each AI attempt may consume Builder quota. Inspect the result after an automated fix: a passing static check means the checked syntax and relative imports passed, not that the app builds, behaves correctly, is secure, or has passing tests.

If you prefer to guide the fix yourself, ask a targeted question instead:

nexus builder ask --project <project-id> "The check reports a missing relative import in src/App.tsx. Fix that import without changing the issue form behavior."
nexus builder check --project <project-id>

Use the path and diagnostic actually printed for your app. After that, open the browser preview and test the affected flow. For serious apps, also run the project's own build, tests, and security review after pulling the code locally.

Edit the generated app in your own editor

Builder files live in the project snapshot, not automatically in your working directory. pull copies the snapshot to an empty local directory and writes a .nexus-builder.json sync manifest:

nexus builder pull --project <project-id> --out ./issue-tracker

Open ./issue-tracker in your editor, inspect its actual file structure, and make a change—for example, adjust the issue form's validation message or add a component. Then sync it back:

nexus builder push --project <project-id> --from ./issue-tracker
nexus builder check --project <project-id>

push includes local text files, including new files, and creates a new Builder checkpoint. It skips .git, node_modules, build output, and .env files. The sync is limited to 200 files and 2 MB of content; symlinks and binary/non-UTF-8 files are not supported. Keep secrets out of Builder files.

If you remove a file that was in the pulled snapshot, push stops and asks you to confirm the deletion:

nexus builder push --project <project-id> --from ./issue-tracker --delete

Use --delete only when you intentionally removed those files. For a single file, you can skip the pull/push cycle:

nexus builder put src/components/IssueCard.tsx --from ./IssueCard.tsx --project <project-id>
nexus builder rm src/components/OldIssueCard.tsx --project <project-id>

The Builder path in put or rm must match the project's file structure. put adds or replaces that file and rm deletes it; neither automatically edits imports elsewhere. Run check after either operation. File changes made through the CLI are shared with the browser Builder.

What if someone edited the app after I pulled it?

push compares the checkpoint recorded by pull with the current project checkpoint. If another Builder chat, browser edit, or file operation changed the app, push rejects your stale copy rather than overwriting those changes. Keep your local directory, pull the newest snapshot into a different empty directory, compare and merge your edits there, then push the merged directory. Do not simply add --delete: that flag confirms missing files, not a stale checkpoint.

Review checkpoints and open the preview

Each successful AI response or file edit produces a Builder checkpoint. To list them:

nexus builder versions --project <project-id>

The output includes message IDs. If you need an earlier file state, choose the intended ID and restore it:

nexus builder revert <message-id> --project <project-id>

Revert saves the restored files as a new checkpoint. It does not erase the intervening history. Review the listed version before reverting because it changes the current snapshot.

To inspect behavior, get the browser Builder URL:

nexus builder open --project <project-id>

Inside chat, /preview prints the same kind of link. Open it in a browser to run the preview, click through the issue list and form, and make sure the result matches your requirements. open only prints the URL; it does not launch a preview inside the terminal.

Deploy the reviewed snapshot

Deployment is explicit. After reviewing the files, running check, and testing the browser preview, deploy the current Builder snapshot:

nexus builder deploy --project <project-id> --name issue-tracker --provider docker
nexus deploy list --project <project-id>

The command creates a deployment from the current files and prints a deployment ID. docker here is a deployment provider, not an AI model. Other providers may be available for your account; for example, --provider gcp_cloud_run selects Google Cloud Run. You can supply --region <region> and --framework <framework> when needed. The CLI uses the project's framework hint, or nextjs if none is set, unless you override it—check the generated app before deployment if that default does not fit.

builder deploy does not automatically run builder check, your package's test suite, or a production build first. It submits a new deployment; it is not an in-place edit of an existing deployment. Deployment uses your normal infrastructure quotas and may incur charges. Check deployment status and logs through the normal deployment commands or dashboard if the build fails.

Quick command map

Common sticking points

• “Where is my project?” The first Builder prompt creates it automatically. Copy the printed project ID. /status shows the ID during chat; use chat --project <id> to resume later.
• “My provider is missing.” Run nexus builder providers. In chat, /provider lists supported providers allowed for your account. Configure one under website Settings → AI Providers if the list is empty.
• “check passed, but preview or deployment failed.” Static checks do not execute the app or replace its build/tests. Inspect the browser preview and deployment logs, then fix the actual runtime or build failure.
• “push says the Builder changed since pull.” Preserve your edits, pull into a new empty directory, merge, and push that newer copy.
• “I typed /help and my shell rejected it.” Slash commands work only at the builder> prompt. From your normal terminal, use nexus builder --help.
• “I pressed Up but yesterday's command is gone.” Chat history is only kept for the current CLI process. The Builder project's files and checkpoints persist; use the project ID to resume them.

For broader platform guidance, see the documentation. For exact Builder flags in your installed CLI, run nexus builder --help or nexus builder <command> --help.

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