@adventurer-tech/guild-cli

Guild CLI for milestones, iterations, tickets, and personal todos. Talks to the Adventurer Public API (apps/api) over HTTPS with x-api-key authentication.

Install

Published to npm as @adventurer-tech/guild-cli on each guild-cli release.

# Global
npm install -g @adventurer-tech/guild-cli
# or
pnpm add -g @adventurer-tech/guild-cli

# One-off
npx @adventurer-tech/guild-cli auth status

Monorepo development

pnpm install
pnpm --filter @adventurer-tech/guild-cli run build
cd packages/guild-cli && pnpm link --global

Authentication

Option A — username/password (local dev, CI, and production CLI automation):

guild auth login --username po --password '<password>'
# or
export GUILD_PASSWORD='<password>'
guild auth login --username po

Fixture users (po, pm, dev1, …) use password Aa123456! after pnpm db:seed (Stargate auth seed). Production users use their Guild account password. Stargate applies per-account login lockout after repeated failures.

Option B — existing API key from Guild Web (Settings → API Keys):

guild auth login --api-key <key>

guild auth status
guild auth logout              # 仅清除本机 ~/.config/guild/credentials.json
guild auth logout --revoke     # 本机清除 + 服务端注销当前 API key

Default API URL: https://api.adventurer.tech. For local API, add --api-url http://localhost:3002.

Credentials are stored at ~/.config/guild/credentials.json (mode 600). Never commit API keys.

Project config

guild config init --project-id <projectId>
guild config show

Project config lives in .guild/config.json (safe to commit; no secrets).

Config priority: CLI flags → env vars → .guild/config.json → ~/.config/guild/credentials.json.

| Environment | API URL | | --- | --- | | Default (no override) | https://api.adventurer.tech | | Local dev | --api-url http://localhost:3002 |

Commands

guild milestone list --json
guild iteration create --title "Sprint 1" --start-at 2026-01-01 --deadline 2026-01-14 --points 40
guild ticket create --type BUG --title "Login failed" --content-file ./bug.md
guild ticket action --no 42 --name take
guild todo list
guild todo create --title "Review PR" --tag review --due 2026-07-31
guild todo complete --id <todoId>

guild todo operates on the current API-key user and does not require .guild/config.json / --project-id. guild todo list returns unified items (personal todos + assigned actions).

API: POST …/@publish|close|… for ticket state; POST …/actions/@take|submit|… for workflow; PUT …/level|stage|… for associations; POST /todos/:id/@complete|@restore for personal todos. See apps/api/docs/custom-verbs.md.

Run guild --help, guild ticket --help, guild todo --help, or guild ticket create --help for full option lists.

Output is JSON by default: { "ok": true, "data": ... } or { "ok": false, "error": { "code", "message" } }.

Skills (Cursor Agent)

Skills live in the public repository adventurer-tech/guild-skills:

npx skills add adventurer-tech/guild-skills -y -g

Monorepo developers: scripts/setup-guild-skills.sh from the repo root.

Release

Version tags: guild-cli-v1.0.0 → @adventurer-tech/[email protected] on npm.

CLI major versions are independent from the API; see CHANGELOG for compatibility notes.