0.5.0 - 2026-10-18

Release Notes

Changed

• Refreshed the frozen contract to Hamstik Public API v1.0.0: the parity ledger
  now classifies all 234 operations (125 newly exposed). hamstik api invoke <operationId> provides contract-aware coverage for method/path resolution,
  context-backed path parameters, documented query parameters, JSON and
  multipart bodies, operation-specific ETags/idempotency, binary downloads,
  dry-run previews, audit records, and structured output. The typed bulk-create
  model also accepts the expanded v1.0.0 request fields and template-backed
  creates whose title is supplied by the server template.

• hamstik agent skill install now installs the complete canonical skill,
  including its three references. Global installs honor HAMSTIK_SKILL_HOME
  as the .agents directory; modified reference files are protected from
  replacement without --force. The skill cookbook and installation guides
  now match the bundled CLI behavior.

Added

• Gated design stub for self update with stable/prerelease channels (CLI-79):
  design/SELF_UPDATE.md documents the intended
  hamstik self update [--channel stable|prerelease] surface, channel
  semantics, verified package replacement (checksum + provenance before any
  write, atomic and recoverable), and the safety constraints — explicit
  opt-in/opt-out, off-by-default automatic checks, no telemetry, and no silent
  network calls. No command or network behavior ships: the design names the
  packaging/release-milestone gate and the activation checklist, and the
  existing channel upgrade steps in design/INSTALL.md
  remain the only supported upgrade path.

• Webhook management (CLI-78): hamstik webhook now manages the Public API
  v1.0.0 Organization webhook surface with list/view/create/edit/delete,
  signing-secret rotation, server-owned test delivery, delivery history, and
  redelivery. The command validates required bodies, ETags, and idempotency
  from the frozen operation contract and never stores returned secrets.

• Server-side workflow automation rules (CLI-77): hamstik rule now manages
  Public API v1.0.0 Organization automation rules with
  list/view/create/edit/delete, run history, server preview, enablement toggle,
  and owner acceptance. The former local-rule proposal is superseded; no local
  evaluator, daemon, or polling event stream is introduced.

• SqueakQL query-plan passthrough and offline cache management (CLI-76):
  work search --explain forwards server-provided query-plan data under the
  response's explain field when the Public API returns it and otherwise
  degrades with a clear message on stderr (or explain.available: false in
  --json); the CLI never computes a cost model and never adds an unsupported
  field to the search request. squeakql cache size reports the local
  saved-query file's path, entry count, and on-disk byte size, and
  squeakql cache clear removes every locally saved query idempotently — both
  work fully offline and require no Organization or credential.

• API cookbook in command help (CLI-75): hamstik commands --cookbook prints
  a copy-pasteable read → search → edit → transition → comment loop with
  placeholder identifiers and safe automation defaults (--json --no-input,
  explicit --org/--project). --json emits the same steps as a versioned
  cookbookVersion: 1 document. The examples are the marker-delimited section
  of the canonical bundled Agent Skill, so the CLI cannot print guidance that
  hamstik agent skill check does not also validate.

• Failed-request journal and replay (CLI-72): when a Public API request
  fails, the CLI appends one redacted JSON line to a local
  request-journal.log capturing the method, path, intended header names, HTTP
  status, server request id, and timing. hamstik replay [--last N] prints the
  most recent entries as a human table or --json without making any network
  request, so a 5xx can be correlated with server-side diagnostics by request
  id. The journal never contains tokens, Authorization values,
  request/response bodies, or query strings; entries older than 7 days are
  dropped and at most 500 are retained, with compaction once the file exceeds
  256 KiB or its oldest entry passes 7 days. hamstik doctor reports the
  effective journal path.

• Support-bundle comparison (CLI-71): doctor --diff <bundle-file> diffs a
  freshly generated local-only support bundle against a previously saved
  doctor --bundle ZIP and reports only what changed. Differences are named
  by check id or JSON path (host, CLI version, context scopes, config
  metadata, and every redacted check), volatile capture noise
  (generatedAt, durationMs, requestId) is ignored, and an identical
  bundle yields an explicit "no differences" result in both human and
  --json output (noDifferences: true). --diff implies --local-only, so
  the comparison makes no network requests and reads no new sensitive data;
  --bundle can be combined to also write the fresh bundle; a missing or
  corrupt baseline fails clearly instead of reporting no differences.

Security

• Updated rustls to 0.23.46 and zip to 9.0.5 to resolve the current RustSec
  advisories. Linux/BSD credential storage now uses the maintained synchronous
  Secret Service backend instead of the unmaintained pre-zbus-6 wire stack;
  secrets remain in the operating system credential store.

Fixed

• The README no longer claims pre-alpha status with packaging "still under
  development"; the status banner now reflects the shipped installer/archive
  channels, the implemented Public API v1.0.0 surface, and the pre-1.0
  breaking-change policy (CLI-80).

• hamstik doctor now omits the proxy check when no proxy environment
  variable is configured instead of showing a confusing skipped row. A
  configured proxy is still reported by variable name with its value hidden;
  NO_PROXY alone does not count as a configured proxy.

• hamstik doctor now reports additive Public API v1 operations as a passing
  compatibility check instead of a warning. The additive operation count
  remains visible, while missing or moved operations required by this CLI
  continue to fail compatibility.

• doctor --bundle no longer prints its "support bundle written to ..."
  confirmation in --json mode, so doctor --json --bundle <PATH> output is
  a single parseable JSON document again.

• Git worktree context discovery (CLI-69): when the .hamstik.toml directory
  walk-up finds nothing and the working directory is inside a git checkout,
  the primary checkout behind a linked worktree is searched
  (git rev-parse --show-toplevel/--git-common-dir), mapping the current
  subtree onto the same relative path in the primary checkout. A linked
  worktree and monorepo Project subtree can therefore reuse the primary
  checkout's config without copying it; explicit flags, environment variables,
  and a worktree-local .hamstik.toml still win.

• Scheduled export and report snapshots (CLI-67): work export --query <SQUEAKQL> (or --query-file/--query-saved) selects a collection of
  Organization Work Items and renders it through the same output contract as
  work list/work search, so --format csv|jsonl|tsv|json|markdown|table,
  --columns, and --jq all apply and --output <PATH> writes exactly the
  bytes a stdout run would print. schedule list|save NAME -- <COMMAND…>|delete
  store the periodic invocation as a plain TOML file under
  <config-dir>/schedules/; the CLI ships no daemon, and an external scheduler
  (cron, systemd timers, Task Scheduler) invokes schedule run NAME, which
  re-executes the stored command through the same binary, context, and output
  mode, so a scheduled run is byte-identical to the equivalent manual
  invocation. Definitions contain only the hamstik argument vector — never
  credentials.

• work dashboard (CLI-65): a read-only, multi-project overview that
  composes the existing work mine read (GET /my/work, restricted to the
  Project set) with one work list read (GET .../projects/{key}/work-items) per configured Project. The Project set
  comes from repeated --project flags, otherwise from a
  dashboard_projects array in .hamstik.toml, otherwise from the resolved
  single Project. Project fetches run with bounded concurrency, and one
  Project's failure is reported in-band (per-section status/error and
  failedSections in --json, a stderr warning in human output) without
  hiding the other Projects' results; the exit code stays 0 for a partial
  snapshot, matching work triage. --mine false omits the My Work section,
  --scope selects the status scope (default open), and the shared
  pagination flags apply to every section. Human output renders one attributed
  table per section; --quiet prints only item keys.

• Deterministic color and terminal-profile negotiation (CLI-60): the global
  --color=auto|always|never flag (with the existing --no-color as the
  never alias) makes ANSI output explicit, and HAMSTIK_NO_COLOR joins
  NO_COLOR/CLICOLOR_FORCE/CLICOLOR under the documented precedence
  flag > environment > auto. HAMSTIK_TERM=auto|unicode|ascii pins the
  decoration profile: ascii emits ASCII stand-ins instead of Unicode
  swatches and separators, suppresses emoji, and fixes the board view width
  so captured CI logs are byte-stable. Default auto-detection is unchanged
  when no flag and neither new environment variable is set, and --json,
  --jsonl, and --tsv remain ANSI-free in every mode.

• work attachment view (CLI-40): preview an image attachment inline on a
  terminal that advertises the Kitty, iTerm2, or SIXEL image protocol,
  without writing a file. Detection is capability-based (KITTY_WINDOW_ID,
  TERM/TERM_PROGRAM markers, and an explicit HAMSTIK_IMAGE_PROTOCOL
  override). The image is only rendered on a TTY in human output; under
  --json/--jsonl/--tsv, --quiet, --no-input, a non-TTY stdout, a
  non-image attachment, an unknown terminal, or an undecodable image, it
  falls back to the unchanged download behavior (--output supported) so
  no raw image or escape-sequence bytes ever reach a text stream.

• Interactive fuzzy picker for ambiguous references (CLI-38): when an
  Organization slug, Project key, or Work Item key supplied to context set,
  org use, project use, work context, or a single-key work view fails
  its exact Public API lookup on a real TTY, the CLI now lists the plausible
  candidates and asks for an explicit choice instead of failing immediately.
  A unique fuzzy match resolves without prompting; cancelling (Esc/Ctrl+C)
  aborts with no changes. The picker never appears under --no-input,
  --json/--jsonl/--tsv, --quiet, or a non-TTY stdin/stdout: those
  paths keep today's exact NOT_FOUND fail-fast behavior and make no
  candidate-list request.

• api rate-limit (CLI-36): one cheap authenticated Public API read that
  reports the current RateLimit-* snapshot so long-running scripts and
  agents can see headroom before hitting a 429. --json --no-input emits a
  stable { "rateLimit": { "limit", "remaining", "resetIn" } | null, "requestId"? } document whose fields mirror api request's
  meta.rateLimit, sourced from the same transport-level parser. The probe
  skips the proactive depleted-window wait that typed reads apply on a
  successful response, and the snapshot is a point-in-time observation
  rather than a guarantee against future rate limits.

• agent validate (CLI-74, also available as agent doctor): offline
  verification of the local agent harness. It lints the installed Agent
  Skill's metadata against the running CLI version (and its command
  references against the live manifest), scans the resolved config directory
  for credential-shaped content — reporting file, line, and kind while never
  printing the value — and, when online, compares the bundled OpenAPI
  snapshot with the live Public API contract. --offline skips the network
  comparison, and an unreachable host is reported as skipped. An outdated
  skill, credential-shaped config content, or a stale snapshot exits 1;
  a clean harness exits 0. It is distinct from hamstik doctor, which
  reports network/diagnostic health.

• work export / work import (CLI-66): Markdown-based handoff and
  migration. work export <KEY> [--comments] [--output <PATH>] writes one
  canonical document — YAML frontmatter (key, title, type, status,
  priority, labels, and optionally links/comments) plus the description
  as the Markdown body, suitable for pasting into a GitHub/GitLab issue;
  --json exposes the same fields as documentVersion: 1. work import --file <PATH|-> reads that document and maps its fields onto the existing
  create/edit requests: a resolvable embedded key updates the item in place,
  otherwise a new item is created with an idempotency key derived from the
  embedded key (or an explicit --idempotency-key), so re-importing the same
  document does not duplicate items. Labels, links, and comments are applied
  through the documented endpoints and reconciled against the current item, and
  --dry-run previews the mapped operations without sending a mutation.

• board view (CLI-64): a read-only, kanban-style board composed entirely
  from the existing Work Item list read (GET .../projects/{key}/work-items, optionally filtered by --sprint). It
  renders width-aware status columns — honouring $COLUMNS, sizing columns
  to their content, and wrapping cards when the board would overflow — with
  --quiet emitting only keys. --json emits a stable boardVersion: 1
  document (scope, columns, itemsFetched, truncated). Columns derive
  from the statuses the server reports on the returned items; items whose
  status is absent or blank render in an explicit missing-status bucket.
  There is no board move: the Public API exposes no board write, and
  workflow changes continue through work transition.

• work bulk run (CLI-62): resumable bulk execution for operation sets larger
  than the single-request 50-operation limit. The runner reads a JSON array or
  streamed JSON-lines operations source (--operations-file -), preflights
  every operation against the existing bulk schema, and sends batches of at
  most 50 through the existing typed bulk envelopes. Each batch's exact request
  body and idempotency key are written to a local JSON-lines journal before the
  request, so an interrupted run resumes (omit --operations-file) by skipping
  completed batches and replaying uncertain ones with the same idempotency key;
  failed batches are never retried automatically and require --retry-failed
  after review. --restart replaces an existing journal. Output states
  explicitly that separate batches are separate requests and not one atomic
  transaction, and the documented journal schema contains no credentials.

• work watch <KEY> (CLI-61): follow a Work Item's activity and comments
  live by polling the existing Public API v1 reads. New entries are rendered
  incrementally within one --interval (default 2s); the first poll starts
  at --since (default: now). Network failures and rate limits back off and
  reconnect with a stderr report, Retry-After is honoured, and
  authentication/authorization failures stop the watch cleanly. Ctrl-C stops
  without a traceback. --notify <COMMAND> runs a hook per new entry with
  HAMSTIK_WATCH_* environment variables, and --json/--jsonl emit one
  compact JSON event per line. work await remains the one-shot condition
  wait; help and docs distinguish the two.

• Output-format ergonomics (CLI-59): the global --format ndjson|jsonl|tsv|csv|table|human|json|markdown umbrella selects the output
  mode by name, and markdown renders a GitHub-flavored table for list-shaped
  output while csv follows RFC 4180 quoting. --fields a,b,c selects and
  orders table columns on every read command (the comma-separated spelling of
  --columns); on the Work Item list commands it remains the server-side
  sparse fieldset and an unknown name now fails locally as a usage error
  listing the valid fields. --json output is unaffected.

Breaking

• The local --format flags that selected a non-output-mode value were
  renamed to free the global --format umbrella: work context --format is
  now the global --format (--format json, --format markdown),
  user avatar --format is --image-format, commands --format is
  --manifest-format, and release audit get --format is --audit-format.

• Release Version support through the typed API client and new CLI commands:
  hamstik release list|view|create|edit|transitions|transition|archive| restore|scope for Project release lifecycle (with If-Match revision
  protection and idempotency keys on every mutation), Work Item release
  membership via release item list|add|remove|replace and
  release bulk-membership (JSON envelope, preflighted to the documented
  1–50 operation bound), release announcements via release announcement current|revision|publish and release announcement draft show|generate|edit|discard, and frozen audit packages via release audit generate|get|list (JSON packages print verbatim; CSV ZIP packages require
  --output and are written atomically).

• Organization Milestone support: hamstik milestone list|view|create|edit|transitions|transition|releases|events with release
  membership via milestone release add|remove (--confirm-remove is
  required to remove a release). Milestone edits and transitions carry the
  exact current ETag plus an idempotency key.

• release archive (and release transition <ID> archived) and
  milestone transition <ID> archived join the destructive-consent gate:
  they require --confirm-destructive or --yes before any request is sent.

• The frozen Public API v1 snapshot now covers the 0.4.0 server contract
  (109 operations; the previous snapshot tracked 78). All 31 new operations
  are classified in openapi/api-parity.json with typed client methods, CLI
  commands, and transport tests, so hamstik doctor no longer reports the
  0.4.0 endpoints as additive.

Install hamstik-cli 0.5.0

Install prebuilt binaries via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/blackboardstudios/hamstik-cli/releases/download/v0.5.0/hamstik-cli-installer.sh | sh

Install prebuilt binaries via powershell script

powershell -ExecutionPolicy Bypass -c "irm https://github.com/blackboardstudios/hamstik-cli/releases/download/v0.5.0/hamstik-cli-installer.ps1 | iex"

Install prebuilt binaries via Homebrew

brew install blackboardstudios/hamstik/hamstik

Download hamstik-cli 0.5.0

File	Platform	Checksum
hamstik-cli-aarch64-apple-darwin.tar.gz	Apple Silicon macOS	checksum
hamstik-cli-x86_64-apple-darwin.tar.gz	Intel macOS	checksum
hamstik-cli-x86_64-pc-windows-msvc.zip	x64 Windows	checksum
hamstik-cli-aarch64-unknown-linux-gnu.tar.gz	ARM64 Linux	checksum
hamstik-cli-x86_64-unknown-linux-gnu.tar.gz	x64 Linux	checksum