Skip to content

v0.6.0 — Official Codecks API (v2.96): one API token

Latest
Latest

Choose a tag to compare

View all tags
@rangogamedev rangogamedev released this 30 Sep 12:07
· 1 commit to main since this release
v0.6.0
254739f
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

codecks-cli now uses the official Codecks API introduced in Codecks v2.96 "The Magic Key: API & 2FA". One long-lived API token replaces the browser-cookie token, the report token and the access key.

Breaking release. The old browser-login header 0.5.x relies on is deprecated and officially retired on 2026-12-31. In practice it already fails: since v2.96, requests come back as if unauthenticated, with empty decks that 0.5.x reports as a misleading [TOKEN_EXPIRED] (#60). Upgrade with the migration guide.

Upgrade in four steps

  1. pip install -U "git+https://github.com/rangogamedev/codecks-cli.git"
  2. In Codecks, open Your Profile → API Tokens and create a Read & write token. Copy it right away; it's shown only once.
  3. Run codecks-cli setup, paste the token, and pick your default deck.
  4. Delete CODECKS_REPORT_TOKEN and CODECKS_ACCESS_KEY from .env and from any MCP, Docker or CI settings.

Highlights

Official API tokens

  • Requests authenticate with Authorization: Bearer cdxut_… (personal token) or cdxat_… (organization token).
  • Setup and startup checks confirm the account resolves for the token. Setup warns, without rejecting the token, if it can't see any projects yet (a new organization, or an organization token with no projects selected).
  • Error messages follow the documented server codes: unrecognised, expired or revoked tokens; personal tokens disabled by an admin; CODECKS_ACCOUNT not matching the token's organization; and missing permissions (a 403 is reported as a permission problem with the server's explanation, instead of "token expired").

Card creation through the official API

  • create, the MCP tools create_card/batch_create_cards, feature, split-features and gdd-sync all use dispatch/cards/create.
  • Cards show you as their author, and the deck is set in the same request.
  • Attachments use the official s3/sign + cards/addFile flow.
  • create --priority a|b|c is now available on the CLI.
  • For personal tokens, your own user is found through the API's loggedInUser query, so hand commands and attachments act as you.
  • gdd-sync sets priority and effort in the create request: one API call per card instead of two.

Default deck

  • New CODECKS_DEFAULT_DECK. setup asks for it once, listing decks as "Deck (Project)". Change it with codecks-cli default-deck <name> [--project <name>].
  • The deck's ID is stored, so renaming the deck keeps working, and same-named decks in different projects can't be confused.
  • create without a deck uses it. If none is set, create stops with a hint instead of making a private, deck-less card.

Fixes found in the post-migration audit

  • No more duplicate sub-cards: Codecks now reports hero cards' childCardInfo as empty, so every hero card showed 0 sub-cards and split-features would split a feature that was already split. Counts now come from the v2.96 count:childCards aggregate. The hero filter uses exists:childCards and also works from the MCP cache. (#64)
  • Your hand is yours: the hand query returned every member's hand, so teammates' cards could show up as yours. It now asks only for your own entries. MCP create_milestone records the token's user as the creator. (#66)
  • Error codes agents can act on: documented API errors map to TOKEN_EXPIRED, SETUP_NEEDED, PERMISSION_DENIED, RATE_LIMITED (retryable), INVALID_QUERY, HTTP_ERROR and NETWORK_ERROR, in MCP responses and CLI JSON errors. Rejected queries show Codecks' error code, path and message. (#67)
  • Rate limiting counts real requests: every Codecks request, not every MCP tool call, now counts against the 40 requests / 5 s limit, including cache warming and batch tools. (#69)
  • No false "token expired" warnings on empty lists. API tokens get a real 401 when rejected. (#68)
  • Docs fixes for get_account and CODECKS_DEFAULT_DECK. (#70)
  • Always acts as you: a temporary Codecks error (rate limit, server hiccup) while looking up your user no longer switches the server to the account owner's hand. Personal API tokens always use their own user, and setup no longer asks "Which user are you?" for them. (#71)

Removed

  • CODECKS_REPORT_TOKEN, CODECKS_ACCESS_KEY, and the generate-token command. Codecks' User Reports feature itself is unchanged; codecks-cli just no longer needs it.
  • --severity on create (and the MCP severity argument) now returns an error. Codecks cards have no severity field; use --priority instead.
  • Python API:
    • cards.create_card is now create_card(title, content, deck_id=None, **fields).
    • api.report_request, api.generate_report_token and attachments.upload_report_files are removed.

Docs and agent setup

  • New migration guide covering breaking changes, API token best practices (personal vs organization tokens, least privilege, expiry dates, one token per machine) and troubleshooting.
  • The setup skill, PM skill, PM playbook and MCP setup-guide prompt are updated for API tokens and the default deck.
  • Install commands now point at GitHub. The package is not on PyPI, so pip install codecks-cli does not work.

Security

  • pyjwt 2.13.0 → 2.15.1: ten advisories fixed.
  • Also released in 0.6.0: the MCP HTTP runner binds to loopback by default; attachment upload fields are validated; CODECKS_ATTACH_ALLOW_DIRS is stricter.

Thanks

Thanks to @AncientNimbus for reporting the v2.96 break and working out its cause: the old header now authenticated as anonymous, which the CLI mislabelled as an expired token. Their first fix, #60, showed the exact failure modes and led directly to this release.

Official Codecks documentation

Full changelog: CHANGELOG.md · PR #61

Assets 2
Loading