@primeuicom/cli

CLI utility for deploying PrimeUI exported projects to a local workspace.

Requirements

• Node.js >=20
• pnpm recommended for local development

Quick Start

Setup without copying a project API key

Run setup from the local directory you want PrimeUI to manage:

npx @primeuicom/cli setup --ai-preset codex

When no saved organization login exists for this environment, setup opens the browser and waits in the same process:

1. Sign in or register using Google, GitHub, or an email sign-in link.
2. Compare the connection code with your terminal or coding-agent chat.
3. Choose your organization and confirm Connect CLI.
4. Setup receives access privately and continues automatically. No command, code, or token needs to be copied back.

This also works from a non-interactive local coding-agent terminal: the agent shows the verification URL and pairing code while the process waits. The user must approve the connection personally. Never ask the agent to approve its own access. Requests expire after ten minutes; Ctrl+C stops waiting. Existing profiles are reused on later setup runs.

To log in separately, or use another device/browser:

npx @primeuicom/cli login
npx @primeuicom/cli login --org acme --no-open

--no-open prints the URL without launching a browser. The private polling secret stays in memory; only the resulting organization profile is stored in ~/.primeui/config.json with owner-only permissions. Login requires HTTPS, except for loopback development origins. Cloud-only chats without a local terminal cannot save a profile on your computer.

The project slug defaults to the current folder name. Override it, the organization, or the target path when needed:

npx @primeuicom/cli setup percents --org pixel-point --project-root . --ai-preset codex

If an unlinked remote project already has the requested slug, setup stops instead of importing its existing page inventory. Reuse it only with explicit intent:

npx @primeuicom/cli setup percents --reuse-project --ai-preset codex

setup safely chooses one of three paths:

| Local target | Result | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Empty directory | Creates the PrimeUI project, exports the complete Next.js starter directly into that directory, installs dependencies, applies the selected AI preset, verifies the project, and optionally initializes Git. | | Existing Next.js project | Creates the PrimeUI project, writes the local .primeui binding, and applies the selected AI preset without replacing application files. | | Already connected project | Keeps the existing project binding and refreshes the selected project-local AI setup. |

Any other non-empty directory is rejected before PrimeUI creates or writes project state. A matching unlinked remote project is also rejected unless --reuse-project is present. In non-interactive agent runs, always pass --ai-preset. Use --no-git when setup should not initialize a repository for an empty directory.

The organization token and project API key stay inside the CLI process. Only .primeui/project.json receives the project-scoped key, and that path is added to .gitignore.

The legacy email-command flow remains available for compatibility and recovery:

npx @primeuicom/cli org bootstrap --email <email> --organization-name <name>
npx @primeuicom/cli org <org-slug> login <pboot-token>

Setup with an existing project API key

npx @primeuicom/cli <api-key>

Skip git initialization and the initial commit:

npx @primeuicom/cli <api-key> --no-git

The command runs a fully autonomous flow:

1. Validates API key format.
2. Authenticates with PrimeUI API v1.
3. Triggers project export.
4. Downloads export ZIP archive.
5. Extracts files into ./<project-name-slug>.
6. Installs project dependencies with detected package manager.

Connect an existing project to PrimeUI:

npx @primeuicom/cli <api-key> connect

For non-interactive usage, pass the AI preset explicitly:

npx @primeuicom/cli <api-key> connect --ai-preset codex
npx @primeuicom/cli <api-key> connect --ai-preset nothing

The command runs:

1. Validates API key format.
2. Authenticates with PrimeUI API v1.
3. Detects project/monorepo root
4. Request project info API endpoint
5. Ensures the root .gitignore ignores .primeui/project.json and .primeui/temp/
6. Generates config schema.
7. Applies the project-local AI setup to the connected target project, unless you explicitly choose nothing or PrimeUI detects an existing supported local setup and preserves it.

{
  "projectId": "project-id-from-primeui",
  "apiKey": "<project-api-key>",
  "targetProjectPath": "./"
}

• If .primeui already exists in current directory chain, command stops and asks to remove existing config manually before reconnect.
• In an interactive terminal, connect prompts for the AI preset when --ai-preset is omitted.
• In a non-interactive terminal, connect accepts --ai-preset <codex|claude|cursor|nothing>.
• If no explicit preset is provided and PrimeUI detects an existing supported local setup in the target project, connect preserves that setup instead of rewriting it immediately.
• If the follow-up AI setup fails, the project still stays connected and the CLI tells you to rerun ai-setup explicitly.

Pull a fresh export into an already connected local project:

npx @primeuicom/cli pull

Optional API key override:

npx @primeuicom/cli <api-key> pull

The command runs:

1. Loads .primeui/project.json from the connected project.
2. Uses the stored API key unless you pass an explicit one.
3. Refuses to continue when git status is not clean.
4. Requires an explicit confirmation before rewriting files.
5. Creates a fresh PrimeUI export and downloads the ZIP archive.
6. Hard rewrites the configured target project path while preserving .git, .primeui, and node_modules.
7. Reinstalls dependencies with the detected package manager.
8. Creates a git commit with the refreshed export state when files changed.

• Passing an explicit API key also refreshes .primeui/project.json with the current project binding.
• If .primeui/project.json is missing in a clean exported project, npx @primeuicom/cli <api-key> pull recreates it before committing the refreshed state.
• If the repository looks like a monorepo and PrimeUI cannot recover the saved target path, run connect explicitly first so you can choose the correct project folder before pull.
• pull is intended for early-stage sync before heavy manual customization.
• pull is not a merge tool. Local files outside the preserved directories can be replaced or removed.

Log in and manage organization API auth:

Use npx @primeuicom/cli login for browser approval. The legacy email flow is also supported:

npx @primeuicom/cli org bootstrap --email <email> --organization-name <name>

Run the one-time login command from your PrimeUI email:

npx @primeuicom/cli org <org-slug> login <pboot-token>

Manage the saved organization profile:

npx @primeuicom/cli org <org-slug> auth status
npx @primeuicom/cli org <org-slug> auth logout
npx @primeuicom/cli org <org-slug> auth revoke
npx @primeuicom/cli org <org-slug> auth rotate

• login exchanges the emailed one-time bootstrap token for a permanent organization login profile.
• org bootstrap requests the email and prints only neutral check-email status.
• The email carries a one-time pboot_ token only.
• Organization profiles are stored in ~/.primeui/config.json, or $PRIMEUI_HOME/config.json when PRIMEUI_HOME is set.
• Profiles are scoped by PrimeUI API base URL and organization slug, so local, staging, and production credentials can coexist.
• The permanent porg_ token is stored locally and must not be printed as a raw secret.
• auth status prints organization/user metadata and token preview only.
• auth logout removes local config state only.
• auth revoke revokes the current server token and removes local config state.
• auth rotate replaces the current server token locally and prints only old/new previews.

List, create, or connect projects from a saved organization profile:

npx @primeuicom/cli org <org-slug> project list
npx @primeuicom/cli org <org-slug> project new <project-slug> --project-root <path>
npx @primeuicom/cli org <org-slug> project connect <project-slug> --project-root <path>
npx @primeuicom/cli org <org-slug> project delete <project-slug>
npx @primeuicom/cli org <org-slug> project delete <project-slug> <pdel-token>

project list prints safe project metadata only. It does not print project API keys, key previews, or project-level commands.

project new uses the saved organization profile, creates an API-owned project, and prints a safe organization-scoped connect command. It does not print, store, or receive the raw project API key in the create response.

project connect uses the saved organization profile, receives the project API key inside the CLI process, writes .primeui/project.json, and updates the root .gitignore. The command prints only the project API key preview.

project delete without a token requests a destructive warning email only. project delete with the emailed one-time token requires an interactive confirmation before it calls the deletion API.

• API-created projects start with bootstrapPagesPending=true.
• Project delete output never prints raw bootstrap, organization, project, or delete tokens.
• npx @primeuicom/cli <project-api-key> creates initial pages once and clears the pending marker.
• npx @primeuicom/cli <project-api-key> connect links the local project without creating pages or clearing the pending marker.

Local development and testing

Configure these environment variables for local development:

• PRIMEUI_API_BASE_URL: PrimeUI API base URL (for example http://localhost:3020 when testing against local Studio API).

Publish

Publish flow includes:

1. Update the package version (usually a patch bump).
2. Publish with the latest tag:

pnpm publish --tag latest

Credits

PrimeUI 2026