v0.12.0

coolhand-cli v0.12.0

October 2026 · npm · GitHub

What's new in v0.12.0

This release adds eight commands: three to read the Coolhand help center (no login needed), search-workloads and cost reporting across the log and template commands, bulk link-feedback, and three to manage a client's uploaded files. It also upgrades coolhand-node to ^0.17.0 and includes a whole-package security review with six hardening fixes. Full flag reference: docs/commands.md.

New commands

Help center, readable from a terminal or an AI agent (#183). Reads are public, so they work before coolhand login. A stored client's key is sent when one is selected (it lifts the anonymous 30-requests-per-minute limit), and is never sent to a --base-url it was not issued for.

coolhand list-help-categories
coolhand search-help-articles "feedback match rate" --per-page 5
coolhand get-help-article what-is-feedback-match-rate

search-workloads (#180) lists and searches workloads, optionally with per-workload cost and performance metrics over a time window.

coolhand search-workloads --include-metrics --days-back 7

The same cost reporting reaches existing commands: search-templates and get-template take --days-back, --since and --until, and search-logs gains --since, --until, --min-cost, --order cost_desc, --project-path and --source-application, and shows a cost per row (n/a when a log could not be priced). fetch-log prints cost and cost breakdown. The new parameters need a backend that supports them; older servers ignore them.

link-feedback (#167) links many feedback records to an optimization in one call, with ids from arguments or a file (--file - reads stdin). Requires a private API key.

coolhand link-feedback <optimization-id> <feedback-id> <feedback-id> --note "Seen in review"
coolhand link-feedback <optimization-id> --file ids.txt --json

Client files (#177): list-client-files, download-client-file and update-client-file list a client's uploaded files, download one to disk, and change its status between draft, published and archived. They require a client admin's private key (coolhand login --scope private). Downloads never overwrite an existing file without --force, and a server-provided filename is reduced to a single safe path segment.

coolhand list-client-files --status published
coolhand download-client-file <file-id> --output ./report.pdf
coolhand update-client-file <file-id> --status archived

Changed

search-logs --include-total (#159) asks the backend for the exact total_count and total_pages instead of the default estimate. Older backends ignore it.

get-template now includes metrics by default, so its output gains a Metrics block and its --json result gains a metrics field. Pass --no-metrics for the previous output.

npm run live-smoke (#181) runs the live smoke test under zsh -ic when zsh is installed, so credentials exported from a zsh profile are visible. It prints its credential source and says why when it skips. This affects contributors only.

coolhand-node upgraded from ^0.14.0 to ^0.17.0 (#182), and mockttp to 4.6.3. Dev dependencies and GitHub Actions were also updated.

Security

A whole-package security review of src/ found no critical or high-severity issues. These fixes shipped:

sync-skills no longer follows a symlinked SKILL.md. Previously a symlink inside a skills directory (for example SKILL.md -> ~/.ssh/id_rsa) would upload the target file to the client's account.

Secret redaction covers more. Session and proxy redaction now also catches SECRET_KEY, auth_key, passphrase, signing_key and encryption_key assignments, credentials embedded in URLs (scheme://user:pass@host), and npm, GitLab, Hugging Face, Google OAuth and PyPI tokens.

Terminal-escape stripping of server-supplied text can no longer be bypassed with nested sequences, and it now removes DCS/APC/PM/SOS and unterminated OSC introducers and other control bytes.

The login callback server answers a malformed request with 400 instead of crashing the login, and sends Referrer-Policy: no-referrer and Cache-Control: no-store. The last-sync request now times out after 10 seconds.

Dependency advisories cleared. npm audit reports 0 vulnerabilities, including proxy-addr, @graphql-tools/utils, ip-address, and basic-ftp (lifted to 6.2.3 with a package override; the CLI does not use FTP).

Breaking changes

None. All new commands and flags are additive. The one behavior change is get-template including metrics by default (see Changed); --no-metrics restores the previous output.