Your CLI is the last thing agents touch.

Copy-paste CLI blocks for the agent era. Trust ladders, killswitches, --json dual mode, audit trails. Battle-tested in CLIs shipping real money and real taxes.

↓ how it works

Installs next-steps + auto-pulls json-mode via registryDependencies.

cligentic

Agent workflow

Two skills. One for building, one for publishing.

Using blocks

Install blocks into your CLI.

Routes intent to the right block and runs bunx shadcn add.

Authoring blocks

Extract a primitive into a new block.

Picks the layer, writes the MDX, registers, rebuilds.

The problem

CLI primitives stopped evolving. Agents didn't.

You've built these 30 times.

Config loader. Session tokens. JSON output. Audit trail. Banner. Every CLI reinvents the same pieces. Copy them once, own them forever.

Agents can't parse your output.

stdout must be JSON. stderr must be hints. No framework ships that discipline. cligentic blocks do.

Safety is hand-rolled every time.

Killswitches. Trust ladders. Intent tokens. Audit trails. None of this exists in clack, oclif, or citty.

How it works

Install. Import. Own.

Run one command

shadcn fetches the block, writes files, installs deps.

Import the block

A local file in your project. No package, no framework.

import { openUrl } from "@/cli/platform/open-url";

const result = await openUrl(url);

Own it forever

Edit it, delete lines, add brand colors. Zero runtime dep on cligentic.

$ grep cligentic package.json
(nothing)

The flagship

stdout is data. stderr is guidance.

Agents parse JSON from stdout and next-step hints from stderr. No system prompt needed.

agent loop

The loop

// agent reads both streams
const data = JSON.parse(stdout);
const hints = stderr.split("\n")
  .map(JSON.parse)
  .filter(o => o.type === "next-step");

// agent picks the next command from hints
run(hints[0].command);

The catalog

20 blocks. Four clusters.

CLUSTER 1

Cross-OS without tears

Open URLs, copy to clipboard, fire notifications. macOS, Linux, Windows, WSL, SSH, CI. Never throws.

detect

Environment detection helpers: `isWsl`, `isCi`, `isHeadlessLinux`, `hasCommand`, `detectMode`, `shouldColor`. Shared across platform and agent blocks. Auto-installed as dependency.

zero deps

open-url

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. Never throws.

zero depschained

copy-clipboard

Copy text to the system clipboard across macOS, Linux (X11 + Wayland), Windows, and WSL. Detects `pbcopy`, `xclip`, `xsel`, `wl-copy`, `clip.exe` automatically. Typed verdict, never throws.

zero depschained

notify-os

Fire a system notification across macOS (`osascript`), Linux (`notify-send`), Windows and WSL (PowerShell). Silently skips in CI. Typed verdict, never throws.

zero depschained

style

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, padVisible, truncateVisible. 256-color semantic palette.

zero depschained

CLUSTER 3

Agent-ready output

`--json` dual mode. Next-step hints on stderr. The loop that lets agents operate CLIs.

json-mode

Dual-rendering output for CLIs serving humans and agents. Auto-detects TTY vs piped, enforces `stdout`/`stderr` discipline, respects `NO_COLOR`. Never calls `process.exit()`.

picocolorschained

next-steps

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-mode`.

picocolorschained

trust-ladder

Approval gate and structured preview renderer for T2/T3 CLI actions. Handles `--yes`, T3 `--confirm`, JSON/non-TTY refusal, and machine-readable AppError failures.

zero depschained

doctor

Health-check pattern for CLI `doctor` commands. Run named checks sequentially with per-check error isolation. Dual output via `json-mode`: structured JSON for agents, `[OK]`/`[FAIL]` table for humans.

zero depschained

api-key-wizard

Interactive first-run wizard for API-key-authenticated CLIs. Masked prompt, live validation against your API, then save via your callback. Generic over validator + save — no assumption about TOML/JSON/keychain storage. Throws typed errors, never calls `process.exit`. Extracted from v0-cli.

@clack/prompts

skill-installer-prompt

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. Returns a discriminated outcome (`installed`, `cancelled`, `skipped`, `error`). Never throws.

@clack/prompts

prompt-secret

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 can fail with a structured error instead of hanging. No runtime dependency.

zero deps

CLUSTER 2

State done right

XDG paths. Atomic writes. Append-only audit logs. Config with profiles. Session tokens.

xdg-paths

XDG Base Directory Spec resolver with macOS (`~/Library`) and Windows (`%APPDATA%`) fallbacks. Gives your CLI canonical `config`/`state`/`cache`/`audit`/`sessions` paths. `APP_HOME` env override for testing.

zero deps

atomic-write

Write files atomically: temp file, `fsync`, rename. Prevents corruption from crashes or concurrent CLI processes. Windows-aware (unlink before rename). Includes `atomicWriteJson` convenience.

zero deps

audit-log

Append-only JSONL audit trail with per-day rotation. Every action gets a timestamped record. Mode `0o600`. Includes `tailAudit` for reading recent records. Battle-tested in hapi-cli and sunat-cli.

zero deps

audit-lifecycle

Two-phase append-only audit lifecycle for dangerous or retryable operations: `beginAudit()` writes pending, then `complete()` or `fail()` appends the final record with the same audit id.

zero deps

banner

Gradient ASCII wordmark for your CLI. Shown on bare invoke or `--help`. Vertical gradient between two hex colors. Respects `NO_COLOR`. Includes minimal block-letter renderer.

zero depschained

config

Profile-aware JSON config loader. Reads from the app's config directory with multi-profile support (`--profile production`). Merge precedence: defaults < profile overrides.

zero depschained

session

Auth token persistence. Load on boot, save after login, clear on logout, check expiry. Atomic writes, `0o600` permissions. The companion of every `login` command.

zero depschained

error-map

Typed `AppError` class with `code`, `name`, `human` message, and `hint`. Maps upstream API errors to actionable messages. `fromHttp()` maps status codes directly. Agents read the `hint` field to self-correct.

zero deps

argv

Minimal POSIX argv parser for zero-framework CLIs. Zero dependencies. Handles `--flag`, `--flag value`, `--flag=value`, `-f`, combined short flags, positional args, `--` stop, and kebab-to-camelCase normalization.

zero deps

global-flags

Standard global flags for agent-first CLIs: `--json`, `--dry-run`, `--profile`, `--no-input`, `--quiet`, `--verbose`. Normalizes raw argv into typed `GlobalFlags`. Includes flag definitions for any parser.

zero deps

telemetry

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. Disabled in CI automatically.

zero deps

CLUSTER 4

Safety flagship

Killswitches. Trust ladders and intent tokens in v0.1. Battle-tested in hapi-cli.

killswitch

Binary safety gate. If `~/.app/KILLSWITCH` exists, all write operations refuse. File exists = stopped. File gone = resumed. One `existsSync` call. Battle-tested in hapi-cli for real brokerage orders.

zero deps