cligentic

Agents need CLIs with safe execution surfaces. cligentic ships the primitives (trust ladders, killswitches, audit logs, --json dual mode) as copy-paste TypeScript blocks you own completely.

bash
bunx --bun shadcn@latest add https://cligentic.railly.dev/r/trust-ladder.json

Why

Every CLI I shipped to production reinvented the same primitives: trust gates, atomic writes, killswitches, JSON dual mode, audit trails. cligentic extracts them.

shadcn model applied to CLI infrastructure. No runtime dependency, no framework lock-in. Install what you need, edit it freely, ship it.

Use the registry in a project

With shadcn@4.18.0 or newer, register cligentic once. In projects without components.json, the CLI stores the registry in package.json.

bash
bunx --bun shadcn@latest registry add '@cligentic=https://cligentic.railly.dev/r/{name}.json'

Then search, inspect, and install blocks by name:

bash
bunx --bun shadcn@latest search @cligenticbunx --bun shadcn@latest view @cligentic/trust-ladderbunx --bun shadcn@latest add @cligentic/trust-ladder

No components.json is required. The copied source and npm dependencies land in your project; cligentic is never added as a runtime dependency.

Install the agent skill

Install the companion skill so your coding agent searches, evaluates, installs, and wires cligentic blocks instead of rebuilding CLI infrastructure from memory:

bash
bunx --bun skills add Railly/cligentic --skill cligentic

For a one-off run without installing it:

bash
bunx --bun skills use Railly/cligentic@cligentic

The skill treats registry installation as the default for TypeScript projects, preserves published contracts, and keeps direct URLs and raw TypeScript as fallbacks.

Install one block without registry setup

Every block is served as a raw .ts file. One curl, no tooling:

bash
curl -o src/cli/agent/trust-ladder.ts https://cligentic.railly.dev/r/trust-ladder.ts

Or let the shadcn CLI place the files and resolve dependencies for you:

bash
bunx --bun shadcn@latest add https://cligentic.railly.dev/r/trust-ladder.json

The shadcn flow resolves the dependency chain to:

src/cli/  agent/    trust-ladder.ts   # TrustLevel enum (T0-T3) + approveGate() + renderPreview()    json-mode.ts      # --json flag detection + structured emit helpers  foundation/    error-map.ts      # AppError with human message + actionable hint

trust-ladder needs json-mode and error-map, because the gate uses JSON-mode detection to know when to throw instead of prompt, and the error type to throw something structured. The CLI pulls those in automatically. With curl, fetch them too, or read the dependency list:

bash
curl -s https://cligentic.railly.dev/r/trust-ladder.json | jq -r '.registryDependencies[]?'

approveGate() is the core: T0/T1 pass through silently, T2 prompts for confirmation, T3 requires --yes --confirm <id>. In --json mode or piped input, any T2+ gate throws instead of prompting, so agents get a structured error, not a hanging prompt.

ts
await approveGate(ctx, preview, { trust: "T2", yes: flags.yes });await placeOrder(order); // only runs if approved

Available blocks

Agent

BlockDescription
trust-ladderT0-T3 approval gate + preview renderer. The core safety primitive.
killswitchFile-based emergency stop. ~/.app/KILLSWITCH exists → all writes blocked.
json-mode--json flag detection + structured stdout/stderr emit helpers.
next-stepsStructured nextSteps hints on stderr. Tells agents what to run next.
doctorPre-flight environment check (deps, auth, connectivity).
api-key-wizardInteractive API key setup with validation and secure storage.
prompt-secretRead a secret from the TTY without echoing it. No runtime dependency.
skill-installer-promptPrompt to install Claude Code / Cursor skills from your CLI.

Foundation

BlockDescription
audit-logAppend-only JSONL logger for every write operation.
audit-lifecycleSession start/end wrappers around the audit log.
atomic-writeWrite to temp file, rename to target. No partial writes.
xdg-pathsXDG Base Directory paths (~/.config, ~/.local/share, ~/.cache).
configJSON config file reader/writer on top of xdg-paths.
sessionSession ID generation and tracking.
error-mapAppError with structured code, human message, and actionable hint.
argvMinimal argv parser without a framework dep.
global-flagsStandard flags (--json, --yes, --dry-run, --verbose).
telemetryOpt-in telemetry with local consent file.
bannerCLI startup banner with version + mode.

Platform

BlockDescription
detectDetect OS, shell, and package manager.
open-urlCross-OS open/xdg-open/start wrapper.
copy-clipboardCross-OS clipboard write.
notify-osDesktop notification via osascript / notify-send / powershell.
styleStyling that respects NO_COLOR in one place, plus visibleWidth / padVisible so tables align once cells carry escapes.

Browse all at .

Used in production

  • broker-cli (private). Agent-first brokerage CLI, moves real money. Uses killswitch, audit-log, session, atomic-write, trust-ladder.
  • . Agent-first v0 Platform API wrapper. Uses audit-log, killswitch, doctor, next-steps, api-key-wizard.
  • . Agent-first SUNAT tax automation. Uses config, xdg-paths, json-mode, next-steps, telemetry.
  • . Reverse-engineers websites into agent CLIs. Uses xdg-paths, config, session.

Stack

Blocks are pure TypeScript. Registry follows the . Anything that speaks bunx --bun shadcn@latest add works.

The site is Next.js + Tailwind 4 + Shiki, deployed on Vercel.

Local development

bash
bun installbun run build          # builds registry/* into site/public/r/*.jsoncd site && bun run dev # http://localhost:3000

To add a block: drop the file in registry/<layer>/<name>.ts, add an entry to registry.json, run bun run build.

License

MIT. See LICENSE [blocked].

Built by at .