Website copy synced to current CLI surface

Documentation

Install cmdhub, get tools, authenticate, and compose adapters with jsonl and agent transforms.

Getting Started

cmdhub adapters share a common command grammar so humans, scripts, and agents can move between tools without relearning each integration from scratch.

Typical flow:

  1. Log in to cmdhub.
  2. Fetch one or more tools with cmdhub get.
  3. Authenticate the tool against its provider.
  4. Start with a list or search command.
  5. Follow up with a short ref such as m1, c1, d1, or p1.
  6. Switch to --jsonl when you want to pipe one command into another.
cmdhub auth login
cmdhub get gmail gcal gdrive mscal msdrive mstodo msoutlook slack notion agent
cmdhub list
cmdhub doctor

Start with the smallest useful workflow. A reliable agent should discover the available command, inspect auth and schema, run a read command, then use the returned short ref or JSONL item for any follow-up action.

Core Patterns

Every adapter is designed around the same operating model:

  • human-readable output for direct terminal use
  • structured json and jsonl output for composition
  • stable short refs for follow-up commands
  • command groups that map closely to the target service
  • doctor, capabilities, schema, and resolve for discovery and debugging

Output Modes

Use human output when a person is reading the result directly:

gmail message list --limit 5

Use json when you want one machine-readable document:

gmail message get m1 --json

Use jsonl when you want to compose commands:

gmail message list --label INBOX --limit 1 --jsonl \
  | slack message get

For agents, prefer --json when the command returns one object and --jsonl when the command returns a stream of objects. Human output is for direct terminal inspection and should not be parsed.

Auth Model

Cmdhub separates account auth from provider auth:

  • cmdhub auth login signs the local machine into the cmdhub account used for registry access, account state, and hosted handoff flows.
  • Provider CLIs such as gmail, gcal, gdrive, slack, notion, mscal, msdrive, msoutlook, and mstodo own their provider credentials.
  • auth status --json is the machine-readable health check for a provider profile.
  • auth whoami --json is the stable identity check before an agent acts on behalf of a user.
  • Profiles are explicit. Pass --profile work or another profile name when the workflow must avoid the default account.

Website account login does not grant Gmail, Calendar, Drive, Slack, Notion, or Microsoft provider permissions. Provider permissions are requested only when the local CLI connects that provider.

Side Effects and Idempotency

Commands that create, update, send, delete, archive, trash, label, upload, share, complete, pin, connect, disconnect, log in, or log out change local or provider state. Treat those as mutating commands.

Before running a mutating command:

  1. Inspect auth with auth status --json.
  2. Inspect the target with a list, search, get, or resolve command.
  3. Inspect the input schema with schema <target> --in --json when available.
  4. Prefer an explicit identifier, short ref, or piped JSONL item over free text.
  5. Use --dry-run when the command exposes it.

Idempotency is command-specific. Read/list/search/get/resolve/schema/doctor commands are expected to be safe discovery commands. Create/send/delete/update style commands should not be retried blindly unless the command output or docs state that retry behavior is safe.

Schemas

Every adapter exposes a schema command when command-level schemas are available. Use schema commands to understand accepted input fields and emitted output fields before composing commands.

gmail schema message.get --out --json
gcal schema event.create --in --json
agent schema --to "gcal event create" --in --json

Generated CLI pages link to a machine-readable catalog.json that lists command paths, stable command anchors, flags, examples, mutation markers, dry-run support, and auth scopes.

Agent-Readable Web Docs

The website publishes the same documentation in browser and agent-readable forms. Browser-default requests get HTML. Requests that prefer text/markdown get Markdown on the same route, and explicit Markdown URLs are available for local browsing:

curl -H 'Accept: text/markdown' http://127.0.0.1:8000/documentation/
open http://127.0.0.1:8000/documentation/index.md
open http://127.0.0.1:8000/cli/gmail/index.md
open http://127.0.0.1:8000/llms-full.txt

CLI pages also expose command catalogs at /cli/<tool>/catalog.json.

Short Refs

List and search commands assign profile-scoped short refs such as m1, t1, c1, d1, p1, f1, or e1. Short refs are intended for immediate follow-up commands in the same profile.

gmail message list --limit 5
gmail message get m1 --json
gmail resolve m1 --json

If a short ref does not resolve, rerun the upstream list/search command for the same --profile, or pass the full provider identifier.

Safe Command Composition

Use a discovery-first pattern when agents compose commands:

gmail auth status --json
gmail message list --label INBOX --limit 1 --jsonl \
  | gmail message get --jsonl \
  | agent explain --to "gcal event create"

Let agent explain, agent validate, and agent adapt --dry-run inspect the contract before piping into a mutating destination command.

Typed Agent Transforms

agent adapt sits between two typed contracts. The upstream CLI emits structured data. The downstream CLI exposes a command-level schema. The agent only needs to bridge the two.

gmail message list --label INBOX --limit 1 --jsonl \
  | agent adapt --to "gcal event create"

Use agent schema, agent explain, and agent validate to inspect or debug the transform before you let it drive a side-effecting command.

CLI Documentation

Each adapter page combines two generated sources:

  • command metadata extracted from the Cobra command tree
  • live examples captured from the eval workspace by the docshots pipeline

That keeps the reference material close to the real CLI surface and makes drift visible in review.

Current Adapters

  • Gmail: inbox, threads, drafts, labels, and attachments
  • GCal: calendars, events, freebusy, and slots
  • Google Drive: files, folders, metadata, trash, and sharing permissions
  • Microsoft Calendar: calendars, events, free/busy windows, and slots
  • Microsoft OneDrive: files, folders, metadata, trash, and sharing permissions
  • Microsoft Outlook: folders, messages, drafts, and attachments
  • Microsoft To Do: task lists, tasks, due dates, and completion
  • Slack: channels, conversations, messages, threads, reactions, and users
  • Notion: databases, pages, blocks, and search
  • Agent: schema-aware transforms between typed command contracts
  • cmdhub: install, registry, auth, config, telemetry, and suite health