Skip to content

docs(cli): add Commonly CLI user guide - #205

Merged
lilyshen0722 merged 1 commit into
mainfrom
docs/cli-guide
Apr 16, 2026
Merged

docs(cli): add Commonly CLI user guide#205
lilyshen0722 merged 1 commit into
mainfrom
docs/cli-guide

Conversation

@lilyshen0722

Copy link
Copy Markdown
Contributor

Summary

A single-page user guide for the `commonly` CLI. No code changes — this closes the gap between the ADRs (the "why") and the per-feature docs (`LOCAL_CLI_WRAPPER.md`, `WEBHOOK_SDK.md`, the "how" for one feature) by giving a top-level "what is the CLI and how do I use it" reference.

Structure

  • Quick start — two-command flow for both the `claude` wrapper and the Python scaffolder
  • Command reference — all subcommands grouped by concept (auth, agents local-CLI, agents webhook-SDK, agents shared, pods, dev)
  • Configuration — the three on-disk files (`~/.commonly/config.json`, `tokens/`, `sessions/`) + env vars
  • `--instance` symmetry — documents the PR fix(cli): resolve --instance symmetrically (saved key OR URL) #202 behaviour (key OR URL)
  • Common workflows — attach claude, write a Python bot, tail a pod, test against local dev
  • Troubleshooting — revoked token, `spawn ENOENT`, Cloudflare UA, etc.

Also

  • `cli/README.md` — one-page pointer to the full guide + run-from-source + test instructions (no such file existed)
  • `docs/README.md` index — adds a `cli/` directory row and a prominent Getting Started link

Test plan

  • Every command + option verified against `cli/src/commands/*.js` at merge time
  • All cross-doc links resolve (LOCAL_CLI_WRAPPER, WEBHOOK_SDK, ADR-004/005/006)
  • CI green (docs-only; should be fast)

🤖 Generated with Claude Code

New docs/cli/README.md — single-page user guide covering:

- Quick start: two-command flow to attach `claude` to a pod; scaffolder
  flow for custom Python agents
- Full command reference, grouped by concept (auth, agents local-CLI,
  agents webhook-SDK, agents shared, pods, dev)
- Config layout: ~/.commonly/config.json + tokens/ + sessions/
- Environment variables
- --instance URL/key symmetry (PR #202)
- Common workflows (attach claude, write a Python bot, tail a pod,
  test against local dev)
- Troubleshooting (revoked token, spawn ENOENT, Cloudflare UA)

Also:
- cli/README.md — one-page pointer to the full guide + quick run-from-source
  and test instructions
- docs/README.md index — adds cli/ row to the directory table and a
  prominent Getting Started link

No code changes. All content is derived from the current shipped
behaviour verified against cli/src/ and docs/agents/.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@lilyshen0722
lilyshen0722 merged commit b59a53f into main Apr 16, 2026
8 checks passed
@lilyshen0722
lilyshen0722 deleted the docs/cli-guide branch April 16, 2026 07:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant