@konspire/cli

Command-line interface for Konspire — share Cursor plans as static, public, comment-ready URLs without giving up the markdown.

Install

npm install -g @konspire/cli

That installs a konspire binary on your PATH.

Commands

konspire login

Sign in via GitHub OAuth and persist your token locally.

konspire login

Opens your default browser to GitHub's OAuth consent screen, captures the returned token via a one-shot localhost callback, and writes it to:

• macOS / Linux: ~/.config/konspire/credentials.json
• Windows: %APPDATA%\konspire\credentials.json

The file is chmod 600 (or the Windows ACL equivalent). The token is HMAC-signed and self-validating — there's no server-side cache to keep synchronized, but revocation takes effect within ~60s.

konspire publish <plan-file>

Publish a markdown plan and get back a stable URL.

konspire publish docs/plans/phase-2-comments.md

Run from inside a GitHub checkout and the CLI fills in --repo, --base-sha, and --branch from origin / HEAD / the current branch. Pass any of them explicitly to override. Outside a git repo (or when origin isn't a github.com URL) --repo and --base-sha are required:

konspire publish docs/plans/phase-2-comments.md \
  --repo konspire-dev/konspire \
  --base-sha abc1234

The CLI:

1. Reads the plan file and any YAML frontmatter (title, todos, etc.).
2. Verifies you have >= write permission on --repo (cached at the API for 5 minutes).
3. Renders the markdown to HTML with code highlighting + Mermaid diagrams.
4. Uploads the result to konspire's CDN.
5. Prints the public URL — https://konspire.dev/p/<slug>_rev<N>.

Republishing the same logical plan ships a new revision; the previous URL stays live forever.

Flags:

| Flag | Required | Notes | | ------------ | ----------------------------------- | -------------------------------------------------------------------------------- | | --repo | only outside a GitHub git checkout | owner/name. Inferred from git remote get-url origin when omitted. | | --base-sha | only outside a git checkout | Inferred from git rev-parse HEAD when omitted. Used for "is this stale?" hints.| | --branch | no | Inferred from the current branch when omitted. | | --api-base | no | Override the API base URL (defaults to production). |

konspire render <input>

Local-only Markdown → standalone HTML conversion. No network, no auth, no publishing — just @konspire/renderer with the same code-block highlighting and Mermaid support the published plans use.

konspire render plan.md --output plan.html
konspire render plan.md --open               # open the result in your browser
konspire render plan.md --strip-frontmatter  # drop the YAML header

Exit codes

| Code | Meaning | | ---- | ------------------------------------------------------------------------------- | | 0 | success | | 1 | unexpected error | | 2 | invalid usage / config error (missing flag, bad value) | | 10 | not authenticated — run konspire login | | 11 | permission denied (no write access on the repo, or banned) | | 12 | rate limited — message includes the retry-after window | | 13 | server / network error — try again, file an issue if it persists |

Links

• Konspire: https://konspire.dev
• API: https://api.konspire.dev/api/default/v1
• Source: https://github.com/konspire-dev/konspire
• Architecture overview: docs/ARCHITECTURE.md

License

MIT