FAQ

Why copy-paste instead of npm install?

Components live in your repo, not in node_modules. You can read them in a single sitting, fork them, delete them, or change the colors directly. There's no @caret/ui version to lock, no breaking change to track. Caret is a starting point, not a runtime dependency. shadcn/ui pioneered this model on the web; Caret applies it to the terminal.

Why Ink, not raw ANSI escape codes?

Ink is React for terminals. It handles input keys, layout, and re-renders for free. Writing the same components against raw stdout with manual cursor positioning works for a single-purpose CLI but falls apart at any non-trivial interaction. Caret is to Ink what shadcn/ui is to Radix — a proven primitive layer to build on, not replace.

Can I build a fullscreen TUI with Caret?

Caret optimizes for transactional CLIs that print and exit (git status, vercel deploy). For fullscreen apps like k9s, lazygit, btop — reach for Ink, Textual, or Ratatui directly. Caret's symbols and principles still translate, but the components are inline-output by design.

How does Caret help AI-generated CLIs?

Two things: every component has a spec at specs/<name>.md, and the project ships a caret.md root file that AI assistants read on every interaction. The result: ask an LLM to "add a deploy command with a spinner" and it produces idiomatic Caret — not five glued-together chalk.red() calls. See AI-native workflow.

Does Caret respect NO_COLOR?

Yes — without you opting in. The capability layer detects NO_COLOR, FORCE_COLOR, TERM=dumb, whether stdout is a TTY, narrow terminal widths, and reduced-motion preferences. Components consult it before painting and fall back through truecolor → 256 → ANSI 16 → plain automatically. See Capability detection.

Can I change the brand color?

Yes — caret.theme.set({ colors: { accent: { default: '#FF6B35' } } }) at startup re-skins everything. The manifesto says the accent should be fixed across your CLI's lifetime — but it's still your CLI, your accent. See Custom theme.

Can I change the symbols?

You can, but you shouldn't. The symbol set (^ ▸ ● ○ ✓ ✗ ⚠ — │) is the brand. A user who recognizes ^ from one Caret CLI should recognize it in every other Caret CLI. The manifesto lists this as one of seven hard rules. See Symbols.

Are there ports to other languages?

Caret is in active design and the TypeScript binding is the first implementation. Ports are explicitly encouraged — every component has a language-agnostic spec at specs/<name>.md precisely so someone can implement it in Go, Rust, Python, or another ecosystem. See Porting Caret.

How do I get updates?

Re-run caret add <name> for a component you already have. The new version overwrites your local copy — diff first if you've forked it. There's no automatic update prompt; Caret won't change your code without you running a command.

Does Caret play sounds?

Never the terminal bell. For long-running tasks, opt into system notifications via caret.notify — they respect OS focus and Do Not Disturb, threshold-gate at 10 seconds by default, and fall back silently when unavailable. This is the manifesto's "Notifications, not beeps" rule.

Why no background colors?

Your terminal has a background already. The user might be on Solarized Light, Dracula, a custom Helmlab theme, or whatever-Vercel-team-uses. Caret doesn't fight the user's environment — it emits foreground colors and attributes only. That's why a Caret CLI looks correct on every terminal without configuration.

Other questions? Open an issue or check Troubleshooting.