@createtodo/cli 0.1.0

package/README.md

@@ -0,0 +1,110 @@
+# createtodo CLI
+
+Manage [createtodo](https://createtodo.com) todos from the terminal. Built for
+scripting and for coding agents: every command prints JSON, so results pipe
+straight into `jq`, git hooks, or an agent's context.
+
+```bash
+npm install -g @createtodo/cli
+ct login
+ct ready
+```
+
+## Authentication
+
+`ct login` prompts for a workspace API key (create one in createtodo under
+**Settings → API Keys**) and stores it in `~/.config/createtodo/auth.json` with
+owner-only permissions. Input is hidden — the key never lands in your
+scrollback.
+
+For CI or containers, skip the login and set the environment variable:
+
+```bash
+export CREATETODO_API_KEY=...
+```
+
+`ct status` shows which workspace and member you are authenticated as.
+
+## Core workflow
+
+```bash
+ct ready                      # actionable work: open, no unresolved blockers
+ct show MZ-123 --relations    # full detail, subtodos, blocking edges
+ct claim MZ-123               # assign to yourself and start it
+ct close MZ-123               # complete it — response lists newly unblocked todos
+```
+
+Closing a blocker tells you what it freed up, so a work loop is just
+`ct ready` → `ct claim` → `ct close` → repeat.
+
+## Creating todos
+
+```bash
+ct create "Fix sync retry loop" -l engineering -p high \
+  -d "Retries hammer the API after a 401 and never back off." \
+  --acceptance="- backoff caps at 60s
+- covered by a regression test"
+
+ct create "Extract the retry helper" --parent MZ-123   # a subtodo
+git log -1 --format=%B | ct create "Follow-up from HEAD" --stdin
+```
+
+Top-level todos created without a description or acceptance criteria come back
+with warnings — thin issues are the ones nobody can pick up later.
+
+## Dependencies
+
+```bash
+ct dep add MZ-124 MZ-123   # MZ-124 waits on MZ-123
+ct dep rm  MZ-124 MZ-123
+```
+
+Cycles are rejected, and `ct ready` hides anything with a live blocker.
+
+## Filtering
+
+```bash
+ct list -l engineering -s "In Progress"   # by list and state
+ct list -a me --needs-human               # flagged for your decision
+ct list --parent MZ-293 -s started        # in-progress subtodos of an epic
+ct ready --label Feature                  # ready work carrying a label
+ct list --updated-after=-P1D              # touched in the last 24 hours
+ct search "retry loop"
+```
+
+Filters compose. Values starting with a dash need the `=` form
+(`--updated-after=-P1D`). Add `--limit` / `--offset` to page, `--full` for every
+field, `--preview` for description snippets.
+
+## Coding agents
+
+```bash
+ct skill install claude-code   # also: codex, cursor, gemini, universal
+```
+
+This installs a skill file teaching the agent the command surface and the
+conventions that matter (reference todos by identifier, never invent one, flag
+human decisions instead of guessing). A CLI is a cheaper agent interface than a
+tool-calling protocol — it returns compact text the agent can filter before it
+costs context.
+
+Hand an agent its own key rather than sharing yours, and it can track work
+across sessions without a chat client running.
+
+## Other commands
+
+| Command | What it does |
+| --- | --- |
+| `ct update <id>` | Change any field; `--decided` clears a human-decision flag |
+| `ct start` / `ct reopen` | Move through workflow states |
+| `ct comment <id> <text>` | Comment (also reads `--stdin`) |
+| `ct label add/rm <id> <label>` | Tag todos |
+| `ct lists` / `ct labels` / `ct states` / `ct members` | Workspace metadata |
+| `ct health` | Stale, orphaned, and thin todos — a pre-PR check |
+| `ct delete` / `ct restore` | Soft-delete and undo |
+
+Run `ct help` for everything and `ct <command> --help` for its flags.
+
+## License
+
+MIT