@primeuicom/cli

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

Requirements

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

Quick Start

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:

Request a one-time login command by email:

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:

npm publish --tag latest

Credits

PrimeUI 2026