Skip to content
WireCatLabsPublic

About

Build CLIs that scripts and AI agents can trust: clean data on stdout and every error as JSON with a stable exit code.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

624 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

cli-base: CLIs that scripts and AI agents can trust

@wirecat/cli-base

Build a command-line tool that a script and an AI agent can trust, in TypeScript on Node or Bun. cli-base keeps data on stdout and everything else on stderr, and turns every failure into one JSON error with a stable exit code.

import { CliError, captureStreams, createRenderer, errorObjectOf, exitCodeOfError, renderError } from "@wirecat/cli-base"

const streams = captureStreams()
createRenderer({ format: "json", color: false, streams }).result({ chats: 2 })

const error = errorObjectOf(new CliError("not_found", "No chat named Alice"))
streams.diagnostic(renderError(error, { cli: "acme", interactive: false }))

streams.stdout // ['{"chats":2}']
streams.stderr // ['{"error":{"code":"not_found","reason":"item.not-found","message":"No chat named Alice","retry":{"safe":false}}}']
exitCodeOfError(error) // 6

No spinner, no ✓ and no warning ever reaches stdout in a machine mode, so acme chats --json | jq always gets clean JSON. captureStreams lets a test prove it.

Built on it: cli-core and 15 WireCat CLIs on top of it, among them tg-cli, max-cli and gcal-cli. cli-testing uses it alone.

Install

npm install @wirecat/cli-base

It is ESM only, for Node 22 and later, and runs on Bun. import it (require() works from Node 22.12). Add commander if you use /skill, and vitest if you use /testing/setup.

API reference · Architecture · Shared tooling · Standards handbook · Changelog · wirecat.dev

npm CI Node Bun License: Apache 2.0

Which package to install

flowchart LR
  cli["Your CLI"] -->|"keeps messages, mail or files to search"| core["@wirecat/cli-core"]
  cli -->|"any other CLI"| base["@wirecat/cli-base"]
  core --> base
  base --> runtime["Node or Bun"]
Loading

Install cli-core when your tool keeps what it reads in a local store and searches it. It brings cli-base along as a peer. For any other CLI, cli-base alone is enough.

Features

  • A script branches on $?, an agent on one JSON object. 15 closed error codes, each with its own exit number: 2 for a bad argument, 4 for a failed sign-in, 6 for not found. Errors are recognised by a brand, not a class, so two installed copies of the package still understand each other's errors.
  • Output that never stops halfway. pretty for a person, json or jsonl for a program, and --json=id,name for only those fields. Output waits until the command succeeds, and past 4 MiB it fails with an error instead of cutting the answer.
  • Tests that never wait. The clock, the sleep, the keyring, env, fetch and the streams are arguments. A timeout test finishes at once, a retry test needs no real backoff, and a keyring test cannot reach a real keychain. /testing has the fakes.
  • Retries that never send twice. Backoff with full jitter, and "no answer came" is never read as "safe to repeat". A write whose outcome is unknown stays unknown and is not retried.
  • The command tree as data for an agent. commands --json gives every command, option and default instead of --help. cli-dev lint checks the tree against the shared vocabulary, and cli-dev audit compares several CLIs.
  • One query language for every list. tasks list state:open priority>1 is parsed by a port of the Lucene 9.12.3 parser, with the fields read from the entity's own schema. An unknown field fails with the list of fields that exist.
  • API clients that never guess. /codegen turns an OpenAPI 3.0 or 3.1 document into types, Valibot schemas and an operation manifest. It stops on an operation it cannot classify as a read, a write or a delete, and never falls back to any.
  • Installs that stay current, and never update unasked. The CLI knows which package manager installed it and prints the command that updates it. wcat tg … runs wcat-tg …, so every WireCat tool is one command away.

Secrets in the OS keyring, on every platform

Credentials resolve environment, then keyring, then file. When the keyring refuses, it warns once and falls through.

Platform Backing store Needs installing
macOS Keychain, via the Security framework nothing, part of the OS
Windows Credential Manager nothing, part of the OS
Linux desktop (GNOME, KDE) Secret Service over D-Bus: gnome-keyring, kwallet nothing on a normal desktop, the keyring must be unlocked
Linux headless, container, WSL, CI usually nothing: no session bus, no secrets daemon falls back to a 0600 file, with one warning on stderr
FreeBSD Secret Service, same as Linux same

No compiler is involved. Prebuilt binaries cover twelve platform triples, and the Linux one speaks D-Bus itself, so libsecret is not needed. Checked against @napi-rs/keyring 2.1.0 on 2026-09-19. Two traps to design for, a shared entry in a throwaway config folder and a locked Linux keyring, are in the API reference.

Development

pnpm test        # vitest, Node
pnpm smoke:bun   # the same exports, run under Bun
pnpm lint
pnpm typecheck
pnpm build

Four runtime dependencies: valibot and its JSON Schema converter, cli-table3 and cross-spawn. A CLI takes its TypeScript, Biome, lefthook, CSpell and CI setup from here, one piece at a time (Shared tooling), and cli-dev replaces the scripts every CLI used to copy. Which checks run on which platform is in Testing.

Releasing

bin/release on main starts release.yml, which runs every check and publishes through npm's trusted publishing with provenance, with no npm token in GitHub. It tags v<version> once npm shows the new version. The steps are in RELEASING.md, and how a release reaches the tools is in the architecture.

Key documents

Document What it answers
Architecture The entry points, the lines this package does not cross, who consumes what
API reference What each entry point holds, with examples
Shared tooling The TypeScript, Biome, lefthook, docs and CI setup a CLI takes from here, and cli-dev
Publishing Where a CLI is published beyond npm, how to prove it, and what has gone wrong
Testing The checks, and what each one is for
Conventions How code here is written
Standards handbook The rules every WireCat CLI follows, one page per area and a new-CLI checklist
CLI standard The messenger rules for tg, max and wa
Roadmap What is being built next for developers on this package
Changelog What each version changed, and what may break callers

History

Up to version 0.20.0 (October 2026) this package was @wirecat/cli-core. That name now belongs to the shared messaging engine, so in older changelogs, plans and issues "cli-core" means this package. Those old @wirecat/cli-core versions (0.18 to 0.20) are deprecated on npm.

Licence

Apache License 2.0.

About

Build CLIs that scripts and AI agents can trust: clean data on stdout and every error as JSON with a stable exit code.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages