CLI commands and output

Run hamstik --help and hamstik <command> --help for the command tree installed on your machine. Use --json --no-input for scripts and pass --org and --project explicitly when changing Work Items. The CLI’s api request command accepts documented Public API v1 paths and uses the same authenticated credential, scope, resource restrictions, and idempotency behavior as its named commands.

Archive and restore

Use the named CLI commands. They read the current revision and apply revision protection and idempotency automatically:

hamstik --json --no-input --org <ORG> --project <PROJECT> work archive <WORK_ITEM_KEY>
hamstik --json --no-input --org <ORG> --project <PROJECT> work unarchive <WORK_ITEM_KEY>
hamstik --json --no-input --org <ORG> project archive <PROJECT> --confirm-destructive
hamstik --json --no-input --org <ORG> project unarchive <PROJECT>

Project archive requires explicit confirmation in non-interactive sessions. Use --dry-run to preview a change. On a revision conflict, inspect the current resource and retry the intended action; do not bypass revision protection.

Work Item archive/unarchive require the work_item:delete scope and effective Project management access; Project archive/unarchive require project:write and an Organization administrator or owner. The Public API passthrough accepts strict empty objects and a current If-Match revision. Repeating the current state is a successful no-op. Discover archived Work Items with ?archived=true on an Organization or Project Work Item collection, and archived Projects with ?archived=true on the Project collection; default collections exclude them. Restoring a Work Item whose Project is archived returns 409 PROJECT_ARCHIVED until the Project is restored. See Work Items and Projects.

Release resources

CLI v0.2.0 exposes Release Versions, Milestones, and audit reports through api request. For example, replace the placeholders with an Organization slug, Project key, and Release UUID:

hamstik --json --no-input api request "/api/v1/organizations/<ORG>/projects/<PROJECT>/releases"
hamstik --json --no-input api request "/api/v1/organizations/<ORG>/projects/<PROJECT>/release-audit-reports" \
  --method POST --field kind=dossier --field "releaseVersionId=<RELEASE_UUID>"

The list requires project:read; report generation requires project:write and Project management access. The CLI supplies an idempotency key for mutations. A returned page.nextCursor is opaque; pass it back unchanged with --query cursor=<CURSOR>. Use the Release API reference and report API reference for request fields, current authorization, bounds, and error behavior. Download ZIP packages from the authorized web report view or a Public API client that handles binary responses.

Work Item cloning

CLI v0.2.0 has no named clone command. Use the Public API bridge to read a same-Project clone preview and create the clone. Cloning requires read access to the source Work Item and create access to its Project, and the CLI supplies an idempotency key for the mutation:

hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/projects/<PROJECT>/work-items/<WORK_ITEM_KEY>/clone"
hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/projects/<PROJECT>/work-items/<WORK_ITEM_KEY>/clone" \
  --method POST --field expectedSourceRevision=7 \
  --field "title=Copy of Implement CLI authentication"

Echo the source.revision from the preview as expectedSourceRevision; a mismatch returns 412 PREVIEW_STALE and creates nothing. See the Work Item API reference for the full field list, link selection, and copy exclusions.

Reactions

The CLI has no named reaction command; reactions are reachable through api request using the documented Public API v1 mutations. Work Item reactions require work_item:write and comment reactions require comment:write:

hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/projects/<PROJECT>/work-items/<WORK_ITEM_KEY>/reactions/heart" \
  --method PUT
hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/projects/<PROJECT>/work-items/<WORK_ITEM_KEY>/comments/<COMMENT_ID>/reactions/eyes" \
  --method DELETE

Reaction keys are thumbs_up, heart, laugh, celebrate, confused, and eyes. Both methods are idempotent and return the target’s {reactions} counts and current-user state. See the Reactions API reference.

Calendar subscriptions

The official CLI does not yet expose named calendar commands. Manage private Project calendar feeds through the documented Public API bridge, using a PAT with calendar:read or calendar:write:

hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/projects/<PROJECT>/calendar-feeds"
hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/projects/<PROJECT>/calendar-feeds" \
  --method POST --field includeSprints=true --field includeDueWorkItems=true
hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/projects/<PROJECT>/calendar-feeds/<FEED_UUID>/rotate" \
  --method POST
hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/projects/<PROJECT>/calendar-feeds/<FEED_UUID>" \
  --method DELETE --idempotency-key revoke-feed

Creation and rotation reveal subscriptionUrl exactly once; reads never return the secret. Send no Idempotency-Key on create and rotate because the response carries a one-time bearer URL that the idempotency store would persist; source changes and revoke accept a key and replay safely. If you lose a create response, recover by revoking the active feed (or rotating it) rather than re-creating — a duplicate create returns 409 CONFLICT. See Calendar subscriptions for bearer-URL handling and external-cache caveats.

Output formats

Use --json, --jsonl, or --tsv for automation. Do not parse the human-readable table format. For the supported version, use hamstik version; route availability follows the server’s live OpenAPI contract, which hamstik api openapi can inspect.

The CLI guide covers authentication and standard Work Item commands. The API resource guide is the contract for resources reached through api request.

Work Item voting

The verified CLI has no named vote command; use the documented api request passthrough (HAM-59). Reading requires work_item:read and setting your own vote requires work_item:write; the CLI supplies the idempotency key:

hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/projects/<PROJECT>/work-items/<WORK_ITEM_KEY>/vote"
hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/projects/<PROJECT>/work-items/<WORK_ITEM_KEY>/vote" \
  --method PUT --field voted=true

The response carries voteCount and hasVoted. There is no toggle and no voter roster; sending voted=false removes your own vote. Retries converge on one committed state. See the Work Item voting API reference.

Attribute support

The verified CLI release is v0.2.0 (build commit cd83f3d3fb94abe6170685d50c49c0b646ce6396). It does not provide named Attribute discovery commands, work edit Attribute flags, or documented Attribute-specific bulk input/projection fields. The public API bridge accepts documented routes; use the Attributes API contract and the server’s generated OpenAPI document to form API requests. For example, the documented bridge supports discovery, Work Item reads, assignment writes, and SqueakQL search through these Public API v1 routes:

hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/attributes"
hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/projects/<PROJECT>/attributes"
hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/projects/<PROJECT>/work-items/<WORK_ITEM_KEY>"
hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/projects/<PROJECT>/work-items" \
  --method POST --field "title=Classify request" \
  --field 'attributes=[{"key":"verified","booleanValue":false}]' \
  --idempotency-key create-classified-request
hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/work-items/search" \
  --method POST --field "query=attribute_verified = FALSE" --field limit=50

For a clear or revisioned edit, use the route’s documented JSON body and pass the current Work Item ETag with --header 'If-Match: "wi-3"'. Definition administration and Project enablement require attribute:write; Project enablement also requires a grant for that Project. Work Item changes and query require their documented Work Item scopes, resource grants, and current user authorization. The bridge is a documented Public API transport and does not add Attribute-specific typed input, safe preview, or bulk parity to named CLI commands. The official CLI is maintained in the separate hamstik-cli repository; its v0.2.0 release is the verified version listed above. The companion repository now has an unreleased implementation of typed Attribute discovery, projections, assignment flags, and bulk input. That implementation follows its SemVer minor-release path as v0.4.0; the release must be published and verified against the matching deployed Public API contract before Hamstik can claim native CLI support. Until then, use the existing api request bridge and do not infer named command support from an OpenAPI route alone. See the CLI release list for published support.

Work Item template support

The verified CLI release does not provide named Work Item template commands. Use the documented Public API bridge to list, read, and manage the same shared Project templates. These routes require project:read for reads and project:write plus Project-management authorization for writes:

hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/projects/<PROJECT>/work-item-templates"
hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/projects/<PROJECT>/work-item-templates" \
  --method POST \
  --field type=bug --field name="Bug reproduction" \
  --field 'defaults={"priority":"high"}' --idempotency-key create-template
hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/projects/<PROJECT>/work-item-templates/<TEMPLATE_UUID>" \
  --method PATCH --header 'If-Match: "template-2"' \
  --field expectedRevision=2 --field name="Renamed template" --idempotency-key rename-template

Create a Work Item from a template by adding templateId to the ordinary Work Item creation route. Omit templateId to apply the configured default, send templateId: null to opt out, or send a template id to select one:

hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/projects/<PROJECT>/work-items" \
  --method POST --field title="Login fails on mobile" \
  --field templateId=<TEMPLATE_UUID> --idempotency-key create-bug

See the Work Item templates API contract for exact fields, precedence, ETags, and errors.

Team support

The verified CLI release does not provide named Team commands. Use the documented Public API bridge to list, create, and manage the same Organization Access Teams and Project Delivery Teams. Access Team reads require organization:read and writes require attribute:write with owner/admin authorization; Delivery Team reads require project:read and writes require project:write plus effective Project admin. Neither team type grants access.

hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/access-teams"
hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/access-teams" \
  --method POST --field name=Platform --idempotency-key create-access-team
hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/access-teams/<TEAM_UUID>/members" \
  --method POST --field userId=<USER_UUID> --idempotency-key add-member
hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/projects/<PROJECT>/delivery-teams" \
  --method POST --field name=Squad --idempotency-key create-delivery-team
hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/projects/<PROJECT>/delivery-teams/<TEAM_UUID>/archive" \
  --method POST --header 'If-Match: "team-2"' --idempotency-key archive-team
hamstik --json --no-input api request \
  "/api/v1/organizations/<ORG>/projects/<PROJECT>/delivery-teams/<TEAM_UUID>/members/<USER_UUID>" \
  --method DELETE --idempotency-key remove-member

Pass the returned page.nextCursor as --query cursor=... for the next page of teams or members. Updates and deletes require an exact If-Match: "team-<n>" revision; archived Delivery Teams cannot gain members and hard deletion is only possible for empty, unreferenced teams. See Teams and the API resources reference for the full contract.