Kosa CLI

kosa is the command-line client for the Kosa API. It exposes authentication, the server's tool catalogue, tool execution, and stored-output retrieval.

Installation

Version 0.1.x is distributed as standalone single-file binaries, one per supported platform, plus a plain JavaScript bundle for Bun users.

Download the binary and matching checksum from the Kosa GitHub Release, then verify and install it:

shasum -a 256 -c kosa-darwin-arm64.sha256
chmod +x kosa-darwin-arm64
mv kosa-darwin-arm64 /usr/local/bin/kosa
kosa --version

An npm or bun install -g @kosa/cli installation is not available in version 0.1.x. You can also run the JavaScript bundle with bun kosa.js <args>.

Authentication

The CLI resolves an API key in this order:

1. --api-key <key> for one invocation. The CLI warns because the value may be visible in shell history unless --api-key-no-warn is also passed.
2. The KOSA_API_KEY environment variable.
3. The credentials file written by kosa auth login.

kosa auth login --api-key kosa_live_...
kosa auth status

The credentials file lives at ${XDG_CONFIG_HOME:-$HOME/.config}/kosa/credentials. The CLI writes it with mode 0600 in a directory created with mode 0700, refuses symlink reads, and refuses a file whose permissions are looser than 0600.

KOSA_INTERNAL_API_KEY is a service-to-service credential. The CLI rejects it at every credential source.

Commands

Authentication

kosa auth login --api-key <key>
kosa auth status
kosa auth logout
kosa auth rotate --api-key <new-key>
kosa auth probe
kosa auth doctor

Tool catalogue

kosa tools list
kosa tools refresh
kosa tools show <name>

The tool catalogue is cached at ${XDG_CACHE_HOME:-$HOME/.cache}/kosa/tools-cache.json with a five-minute freshness window. Use --no-cache to bypass the cache for one invocation.

Run a tool

kosa run <tool-name> --input '<json>'
kosa run <tool-name> --input @path.json
kosa run <tool-name> --input -
kosa <tool-name> --<field> <value>

When the server returns an output_id, the CLI writes output_id=<id> to stderr even under --quiet, so the stored result remains recoverable.

Stored outputs

kosa output get <output_id>
kosa output export <output_id>
kosa output feedback <output_id> --vote helpful [--text "..."]

Versioning

Version 0.1.x provides the core auth, tools, run, output, and auto-derived per-tool command surfaces. kosa --version reports the semantic version, git SHA, and detected install method.