---
name: "@cligentic"
slug: "cligentic"
description: "Copy-paste TypeScript primitives for agent-first CLIs: trust ladders, killswitches, JSON mode, audit logs, and cross-platform utilities."
category: "AI/chat UI"
tags: ["ai", "auth", "buttons", "design-system", "forms", "hooks", "maps", "overlays"]
framework: "react"
license: "MIT"
author: "Railly"
website: "https://cligentic.railly.dev"
github: "https://github.com/Railly/cligentic"
registry: "https://cligentic.railly.dev/r/registry.json"
pro: false
pro_url: null
github_stars: 3
component_count: 24
generated_at: "2026-09-21T01:50:16.753Z"
---

# @cligentic

Copy-paste TypeScript primitives for agent-first CLIs: trust ladders, killswitches, JSON mode, audit logs, and cross-platform utilities.

## Links

- Website: https://cligentic.railly.dev
- GitHub: https://github.com/Railly/cligentic
- Registry JSON: https://cligentic.railly.dev/r/registry.json
- Directory page: https://sh4dcn.vercel.app/registry/cligentic
- This file: https://sh4dcn.vercel.app/md/cligentic.md

## Install

```sh
# add the whole registry (shadcn CLI)
npx shadcn@latest add https://cligentic.railly.dev/r/registry.json
pnpm dlx shadcn@latest add https://cligentic.railly.dev/r/registry.json
bunx shadcn@latest add https://cligentic.railly.dev/r/registry.json
# clone the source repo
git clone https://github.com/Railly/cligentic.git
# fetch the raw registry index
curl -s https://cligentic.railly.dev/r/registry.json
```

## Components (24)

| name | type | description | install |
| --- | --- | --- | --- |
| detect | registry:file | Environment detection helpers: `isWsl`, `isCi`, `isHeadlessLinux`, `hasCommand`, `detectMode`, `shouldColor`. Shared across platform and agent blocks. Auto-ins… | `npx shadcn@latest add https://cligentic.railly.dev/r/detect.json` |
| open-url | registry:file | Open a URL in the user's default browser across macOS, Linux, Windows, WSL, SSH, and headless CI. Respects `BROWSER` env var. Fallback chain with manual print.… | `npx shadcn@latest add https://cligentic.railly.dev/r/open-url.json` |
| json-mode | registry:file | Dual-rendering output for CLIs serving humans and agents. Auto-detects TTY vs piped, enforces `stdout`/`stderr` discipline, respects `NO_COLOR`. Never calls `p… | `npx shadcn@latest add https://cligentic.railly.dev/r/json-mode.json` |
| next-steps | registry:file | Post-command guidance for agents and humans. Emit structured `next-step` hints to `stderr` as NDJSON for agents, formatted block for humans. Chains with `json-… | `npx shadcn@latest add https://cligentic.railly.dev/r/next-steps.json` |
| trust-ladder | registry:file | Approval gate and structured preview renderer for T2/T3 CLI actions. Handles `--yes`, T3 `--confirm`, JSON/non-TTY refusal, and machine-readable AppError failu… | `npx shadcn@latest add https://cligentic.railly.dev/r/trust-ladder.json` |
| copy-clipboard | registry:file | Copy text to the system clipboard across macOS, Linux (X11 + Wayland), Windows, and WSL. Detects `pbcopy`, `xclip`, `xsel`, `wl-copy`, `clip.exe` automatically… | `npx shadcn@latest add https://cligentic.railly.dev/r/copy-clipboard.json` |
| notify-os | registry:file | Fire a system notification across macOS (`osascript`), Linux (`notify-send`), Windows and WSL (PowerShell). Silently skips in CI. Typed verdict, never throws. | `npx shadcn@latest add https://cligentic.railly.dev/r/notify-os.json` |
| xdg-paths | registry:file | XDG Base Directory Spec resolver with macOS (`~/Library`) and Windows (`%APPDATA%`) fallbacks. Gives your CLI canonical `config`/`state`/`cache`/`audit`/`sessi… | `npx shadcn@latest add https://cligentic.railly.dev/r/xdg-paths.json` |
| atomic-write | registry:file | Write files atomically: temp file, `fsync`, rename. Prevents corruption from crashes or concurrent CLI processes. Windows-aware (unlink before rename). Include… | `npx shadcn@latest add https://cligentic.railly.dev/r/atomic-write.json` |
| audit-log | registry:file | Append-only JSONL audit trail with per-day rotation. Every action gets a timestamped record. Mode `0o600`. Includes `tailAudit` for reading recent records. Bat… | `npx shadcn@latest add https://cligentic.railly.dev/r/audit-log.json` |
| audit-lifecycle | registry:file | Two-phase append-only audit lifecycle for dangerous or retryable operations: `beginAudit()` writes pending, then `complete()` or `fail()` appends the final rec… | `npx shadcn@latest add https://cligentic.railly.dev/r/audit-lifecycle.json` |
| banner | registry:file | Gradient ASCII wordmark for your CLI. Shown on bare invoke or `--help`. Vertical gradient between two hex colors. Respects `NO_COLOR`. Includes minimal block-l… | `npx shadcn@latest add https://cligentic.railly.dev/r/banner.json` |
| config | registry:file | Profile-aware JSON config loader. Reads from the app's config directory with multi-profile support (`--profile production`). Merge precedence: defaults < profi… | `npx shadcn@latest add https://cligentic.railly.dev/r/config.json` |
| session | registry:file | Auth token persistence. Load on boot, save after login, clear on logout, check expiry. Atomic writes, `0o600` permissions. The companion of every `login` comma… | `npx shadcn@latest add https://cligentic.railly.dev/r/session.json` |
| error-map | registry:file | Typed `AppError` class with `code`, `name`, `human` message, and `hint`. Maps upstream API errors to actionable messages. `fromHttp()` maps status codes direct… | `npx shadcn@latest add https://cligentic.railly.dev/r/error-map.json` |
| argv | registry:file | Minimal POSIX argv parser for zero-framework CLIs. Zero dependencies. Handles `--flag`, `--flag value`, `--flag=value`, `-f`, combined short flags, positional … | `npx shadcn@latest add https://cligentic.railly.dev/r/argv.json` |
| global-flags | registry:file | Standard global flags for agent-first CLIs: `--json`, `--dry-run`, `--profile`, `--no-input`, `--quiet`, `--verbose`. Normalizes raw argv into typed `GlobalFla… | `npx shadcn@latest add https://cligentic.railly.dev/r/global-flags.json` |
| telemetry | registry:file | Anonymous usage tracking. Opt-out via `CLI_NO_TELEMETRY=1` or `DO_NOT_TRACK=1`. Local JSONL logging + optional remote POST. Never throws, never blocks. Disable… | `npx shadcn@latest add https://cligentic.railly.dev/r/telemetry.json` |
| doctor | registry:file | Health-check pattern for CLI `doctor` commands. Run named checks sequentially with per-check error isolation. Dual output via `json-mode`: structured JSON for … | `npx shadcn@latest add https://cligentic.railly.dev/r/doctor.json` |
| killswitch | registry:file | Binary safety gate. If `~/.app/KILLSWITCH` exists, all write operations refuse. File exists = stopped. File gone = resumed. One `existsSync` call. Battle-teste… | `npx shadcn@latest add https://cligentic.railly.dev/r/killswitch.json` |
| api-key-wizard | registry:file | Interactive first-run wizard for API-key-authenticated CLIs. Masked prompt, live validation against your API, then save via your callback. Generic over validat… | `npx shadcn@latest add https://cligentic.railly.dev/r/api-key-wizard.json` |
| skill-installer-prompt | registry:file | Post-init hook that offers to install a companion agent skill (Claude Code / Cursor / MCP-aware). Clack confirm plus a subprocess spawn with inherited stdio. R… | `npx shadcn@latest add https://cligentic.railly.dev/r/skill-installer-prompt.json` |
| prompt-secret | registry:file | Read a secret from the TTY without echoing it. Raw mode, one dot per keystroke, handles backspace and Ctrl-C. Returns null when there is no TTY so the caller c… | `npx shadcn@latest add https://cligentic.railly.dev/r/prompt-secret.json` |
| style | registry:file | Terminal styling that respects NO_COLOR and non-TTY in one place, plus the width helpers a table needs once cells contain escape codes: visibleWidth, padVisibl… | `npx shadcn@latest add https://cligentic.railly.dev/r/style.json` |

## For AI agents

```text
You are adding components from @cligentic to a shadcn-compatible project.
1. Read this file (https://sh4dcn.vercel.app/md/cligentic.md) for the component list.
2. Fetch the machine-readable index: https://cligentic.railly.dev/r/registry.json
3. Install a single component with its install command from the table above.
4. Full structured record: https://sh4dcn.vercel.app/json (library slug: cligentic).
```