# 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.

```bash
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:

```bash
gmail message list --limit 5
```

Use `json` when you want one machine-readable document:

```bash
gmail message get m1 --json
```

Use `jsonl` when you want to compose commands:

```bash
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.

```bash
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:

```bash
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.

```bash
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:

```bash
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.

```bash
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