cligentic

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.

The problem

CLI primitives stopped evolving. Agents didn't.

01

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.

02

Agents can't parse your output.

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

03

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.

01

Run one command

shadcn fetches the block, writes files, installs deps.

02

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);
03

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

16 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
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
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
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. Agents read the `hint` field to self-correct.

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