assistant-ui CLI

Command-line tool for adding shadcn-style components to your project, scaffolding a new app, and keeping your assistant-ui packages up to date.

Installation

Run via your package manager of choice; nothing to install globally:

npx assistant-ui@latest <command>
pnpm dlx assistant-ui@latest <command>
yarn dlx assistant-ui@latest <command>
bunx assistant-ui@latest <command>

Common tasks

# scaffold a new Next.js project
npx assistant-ui@latest create my-app

# scaffold a minimal project
npx assistant-ui@latest create my-app --template minimal

# scaffold from a feature example
npx assistant-ui@latest create my-app --example with-ai-sdk-v7

# scaffold an Expo / React Native project
npx assistant-ui@latest create my-app --native

# scaffold a React Ink terminal project
npx assistant-ui@latest create my-app --ink

# add assistant-ui to an existing project
npx assistant-ui@latest init

# initialize non-interactively for CI or agent flows
npx assistant-ui@latest init --yes

# add a component
npx assistant-ui@latest add thread

# update all @assistant-ui/* and assistant-* packages
npx assistant-ui@latest update

# run codemods after a major version bump
npx assistant-ui@latest upgrade

# print env + version info for a bug report
npx assistant-ui info

init falls back to create when no package.json is found, so a single command works for both new and existing projects. Use init --yes for CI and agent flows where prompts are not available.

Templates

create scaffolds from named templates: default (AI SDK), minimal, cloud, cloud-clerk, cloud-harness, langchain, mcp, eve. Pass -t <name>, pass --example <name> for examples such as with-ai-sdk-v7, use --native for Expo / React Native, use --ink for React Ink, or pass --preset <url> to scaffold from an assistant-ui.com playground link.

Shared cloud chat

npx assistant-ui@latest cloud setup multiplayer-chat
cd multiplayer-chat
npm run dev

Setup signs you in through your browser, selects or creates your organization and project, provisions a hosted harness, and installs the shared chat starter. Add your OPENAI_API_KEY to the generated .env.local before starting the app. Open http://localhost:3000/#main in two browsers. Both clients share the conversation and see replies as they stream. Share this chat copies the current conversation's URL.

Select resources explicitly for a script or agent:

npx assistant-ui@latest cloud setup multiplayer-chat --org team --new-project hackathon-chat --backend-url http://localhost:3000/api/chat --yes

Use --project <id-or-slug> for an existing project. A hackathon access code can be supplied with --access-code <code> or ASSISTANT_UI_ACCESS_CODE. --use-npm, --use-pnpm, --use-yarn, and --use-bun select the installer; --skip-install leaves dependency installation to you. For a hosted app, pass its HTTPS chat endpoint as --backend-url during initial setup. If you deploy a chat first configured locally, update its backend allowlist in the Cloud dashboard and its backendUrl in .assistant-ui/cloud.json, then rerun setup with the same HTTPS --backend-url. Existing conversations keep their original backend; open the deployed app with a fresh thread fragment such as #deployed-chat, then use Share this chat.

The project API key stays in .env.local, with owner-only permissions and a Git ignore entry. .assistant-ui/cloud.json stores the selected project and harness IDs. Browser clients receive short-lived credentials from the app's server and share the hackathon user. Add your application authentication to /api/credential when the chat needs individual users or private access.

Run npx assistant-ui@latest cloud setup . from an existing cloud-harness starter to resume setup. Existing environment values are preserved; conflicting cloud settings produce an error. npx assistant-ui@latest cloud login signs in separately and npx assistant-ui@latest cloud logout revokes the saved CLI login.

Every other cloud subcommand runs on Assistant Cloud: the CLI sends it to the cloud management server (ASSISTANT_UI_CLOUD_URL, default https://cloud.assistant-ui.com) with the saved login and prints the answer, so new commands arrive without a CLI update. Run npx assistant-ui@latest cloud help for the current list and cloud help <command> for one command's options; cloud help login, cloud help logout and cloud help setup are answered locally with their flags. The commands cover organizations and projects (orgs, projects list, show, set, create), API keys, hosted harnesses (harnesses list, show, live, create, update) and Pinboard Workers (workers, deployments, routes). Every command takes --json, and exits 0 on success, 1 on an error and 2 on a usage error.

Inside a directory set up with cloud setup, commands that take --org or --project default to the organization and project in the nearest .assistant-ui/cloud.json; pass the flags to act on another one.

Agents never run destructive commands. Deleting a project or harness, shortening data retention and moving a Pinboard Worker's live traffic change nothing from the CLI: those commands print the dashboard link (or the API call) for a person to act on. In a terminal the CLI also opens the link; pass --no-open to only print it.

When an agent is installing from an active setup wizard, pass its setup-agent URL with --setup-url <url> to cloud login or cloud setup. The wizard shows the device approval code and sends you to Accounts for explicit consent, then returns to the same setup. The CLI polls Accounts directly and saves credentials locally with owner-only permissions; tokens never pass through the wizard or its generic secret inputs. Cancelling the sign-in question or setup cancels pending login. Returning from Accounts alone does not complete login.

Before the npm patch is released, use the verified wizard sign-in prerelease with your active setup-agent connection URL:

npx --yes --package=https://www.assistant-ui.com/downloads/assistant-ui-wizard-login-ea9aae48e.tgz assistant-ui cloud login --setup-url "<active-setup-agent-url>"

Documentation

Full command reference, flags, and template details at assistant-ui.com/docs/cli.