@astralkit/cli

Install and manage AstralKit UI components, boosters, and workflows in your React and Next.js projects.

Quick Start

# 1. Get your API key from https://astralkit.com/account

# 2. Initialize AstralKit in your project
npx @astralkit/cli init --api-key ak_YOUR_KEY

# 3. Add a component
npx @astralkit/cli add button-sizes --api-key ak_YOUR_KEY

After init, your API key is saved locally — no need to pass it again:

astralkit add pricing-table
astralkit add sidebar-light
astralkit list

What Init Does

npx @astralkit/cli init --api-key ak_YOUR_KEY

1. Installs astralkit — design tokens, CSS utilities, and cn() helper as a real npm dependency
2. Detects your framework — Next.js or React (auto-detected from project files)
3. Detects Tailwind version — v3 or v4, writes the correct CSS imports
4. Detects TypeScript — serves .tsx or .jsx accordingly
5. Updates your CSS — adds @import "astralkit/theme" and @import "astralkit/utilities" to your globals.css
6. Creates astralkit-ai-rules.md — paste into Cursor, CLAUDE.md, etc.

No config file is created. Everything is auto-detected on every command.

Commands

astralkit init

Initialize AstralKit in your project.

astralkit init --api-key ak_YOUR_KEY
astralkit init --framework react
astralkit init --dir src/components/ui

| Flag | Description | |------|-------------| | --api-key <key> | Your API key (from astralkit.com/account) | | --framework <fw> | Override framework detection (react, nextjs) | | --dir <path> | Component output directory (default: src/components/ui) |

astralkit add <name>

Add a component, booster, or workflow to your project. The CLI auto-detects the content type — no flags needed.

# Just type the name — the CLI figures out what it is
astralkit add avatar-verified          # → found as component, installs directly
astralkit add auth-system              # → found as booster, installs directly
astralkit add ai-saas-starter          # → found as workflow, scaffolds directly

Smart detection:

• Searches all registries (components, boosters, workflows) simultaneously
• If found in one → installs directly
• If found in multiple → prompts you to choose
• If not found → suggests similar names ("Did you mean?")

You can still use explicit flags to skip detection:

astralkit add auth-system --booster          # skip detection, install as booster
astralkit add crm --workflow --overlay       # merge workflow into current project
astralkit add pricing-table --framework react

| Flag | Description | |------|-------------| | --api-key <key> | Your API key | | -f, --framework <fw> | Framework version (react, nextjs) | | --dir <path> | Override output directory | | --overwrite | Overwrite existing files | | --booster | Install a booster | | --workflow | Scaffold a workflow | | --overlay | Merge workflow into current project | | --dry-run | Preview without writing files |

astralkit remove <name>

Remove a previously installed component, booster, or workflow.

astralkit remove auth-system
astralkit remove pricing-table --force    # skip confirmation

astralkit list

Browse available content.

astralkit list                    # components
astralkit list --boosters         # boosters
astralkit list --workflows        # workflows
astralkit list --category forms
astralkit list --pro              # pro-only items

astralkit search <query>

Search by name or description.

astralkit search "pricing table"
astralkit search "stripe" --boosters

astralkit diff <name>

Compare your local version against the latest.

astralkit diff button-sizes

astralkit update <name>

Update a component to the latest version.

astralkit update button-sizes
astralkit update button-sizes --force

astralkit whoami

Show your authentication status and plan.

astralkit whoami

astralkit login / astralkit logout

Browser-based authentication (alternative to --api-key).

astralkit login       # opens browser
astralkit logout      # clear stored token

Authentication

API key (recommended):

Get your key from astralkit.com/account. Pass it once with --api-key — it's saved to ~/.astralkit/config.json for future commands.

astralkit init --api-key ak_YOUR_KEY

Browser login (alternative):

astralkit login

CI/CD:

Set the ASTRALKIT_API_KEY environment variable:

export ASTRALKIT_API_KEY=ak_YOUR_KEY
astralkit add button-sizes

Content Types

| Type | Description | Install Location | |------|-------------|------------------| | Components | Single UI elements (Button, Card, Table) | src/components/ui/ | | Boosters | Feature modules (Auth, Stripe, File Upload) | src/lib/<name>/ + src/components/<name>/ | | Workflows | Complete app scaffolds (SaaS Starter, CRM) | New directory or --overlay into current |

Framework Support

The CLI is for React and Next.js projects. HTML users copy components directly from astralkit.com.

| Detection | Signal | |-----------|--------| | Next.js | next.config.* found | | React | react in package.json dependencies | | TypeScript | tsconfig.json found → .tsx files | | JavaScript | No tsconfig → .jsx files |

Package Manager Support

Auto-detected from lockfiles:

| Lockfile | Package Manager | |----------|----------------| | bun.lockb / bun.lock | bun | | pnpm-lock.yaml | pnpm | | yarn.lock | yarn | | (default) | npm |

What Gets Installed

After astralkit init, your project has:

node_modules/astralkit/        ← real npm dependency
├── astralkit-theme.css        ← design tokens
├── astralkit-utilities.css    ← utility classes
├── lib/utils.js               ← cn() function
└── package.json

src/components/ui/             ← components go here
astralkit-ai-rules.md          ← AI coding rules

Your globals.css:

@import "tailwindcss";
@import "astralkit/theme";
@import "astralkit/utilities";

Teammates clone and run npm install — everything works. No astralkit init needed in CI.

Free vs Pro

| | Free | Pro | |---|---|---| | Components | 10/month | Unlimited | | Frameworks | React, Next.js | React, Next.js | | Boosters | — | All | | Workflows | — | All |

Upgrade at astralkit.com/pricing.

Environment Variables

| Variable | Description | |----------|-------------| | ASTRALKIT_API_KEY | API key for CI/CD (skips interactive auth) | | ASTRALKIT_API_URL | Override API base URL (development only) | | ASTRALKIT_LOGIN_PORT | Override callback port for login (default: 9876) |

Troubleshooting

Port 9876 in use:

ASTRALKIT_LOGIN_PORT=9877 astralkit login

Token expired:

astralkit init --api-key ak_YOUR_NEW_KEY

Dependency conflicts:

npm install <package> --legacy-peer-deps

Requirements

• Node.js 18+
• React or Next.js project
• An AstralKit account for premium content

Links

• AstralKit
• Components
• Pricing
• Documentation
• Support