# Agent Manual

The full operating model for cmdhub tools: output modes, short refs, auth, schemas, and safe composition.

New here? Start with [Getting Started](/documentation/) first. This page is the
reference you come back to.

## The operating model

Every tool follows the same shape, so once you learn one you can move between
them without relearning each from scratch:

- readable output for working in the terminal
- structured `json` and `jsonl` output for scripting and composition
- stable short refs (`m1`, `c1`, `d1`) for follow-up commands
- command groups that mirror the real service (messages, threads, events, files)
- discovery commands — `doctor`, `capabilities`, `schema`, `resolve` — to inspect
  before acting

## Output modes

Use the plain, readable output when a person or agent is reading the result
directly:

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

Use `--json` when scripting, parsing, or inspecting every structured field from
one response:

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

Use `--jsonl` for streams of items that feed another command. The upstream list
or search command emits one record per line; the downstream command reads them:

```bash
gmail message list --inbox --limit 5 --jsonl \
  | gmail message get
```

Rule of thumb: plain output for reading, `--json` for strict parsing, `--jsonl`
for piping records into a follow-up command.

## Short refs

List and search commands assign short refs such as `m1`, `t1`, `c1`, `d1`, or
`e1`. They are scoped to a profile and meant for immediate follow-up, so you
never have to copy a long provider ID by hand:

```bash
gmail message list --inbox --limit 5
gmail message get m1 --view full
gmail resolve m1 --json
```

If a short ref no longer resolves, rerun the list or search command for the same
`--profile`, or pass the full provider identifier.

## Auth model

cmdhub keeps your account login separate from each app's login:

- `cmdhub auth login` signs the machine in to your cmdhub account, used for the
  registry, account state, and hosted handoff.
- Each tool — `gmail`, `gcal`, `gdrive`, `slack`, `notion`, and the rest — owns
  its own provider credentials.
- `gmail auth status` (add `--json` in scripts) is the health check for a tool.
- `gmail auth whoami` confirms which account you are about to act as.
- Profiles are explicit. Pass `--profile work` when a workflow must avoid the
  default account.

Signing in to your cmdhub account does not grant Gmail, Calendar, Drive, or any
other provider permission. Those are requested only when the local tool connects
that provider.

## Discovery and schemas

Before composing or mutating, inspect what a command accepts and returns:

```bash
gmail auth status            # is this tool ready?
gcal capabilities            # what can this tool do?
gcal schema event.create --input    # what fields does this command take?
gmail schema message.create --input --json
```

Tools expose a `schema` command wherever command-level schemas exist. Use it to
learn the accepted input fields and emitted output fields before you build on a
command.

## Side effects and safety

Commands that **create, update, send, delete, archive, label, upload, share, or
connect** change real data. Treat them as mutating, and look before you act:

1. Confirm the account with `auth status`.
2. Confirm the target with a `list`, `search`, `get`, or `resolve` command.
3. Check the input fields with `schema <target> --input` when available.
4. Prefer an explicit identifier, short ref, or piped record over free text.
5. Use `--dry-run` when the command offers it.

Reading commands (`list`, `search`, `get`, `resolve`, `schema`, `doctor`) are
safe to repeat. Mutating commands should not be retried blindly unless the output
or docs say retrying is safe.

## Composing commands

The reliable pattern is discovery first, then a piped stream into the next
command:

```bash
gmail auth status
gmail message list --inbox --limit 1 --jsonl \
  | gmail message get
```

Keep the upstream command in `--jsonl` so it emits records, and let the
downstream command read them. Inspect with `schema` before any step that changes
data.

## Where the docs live

Every page on this site is published in two forms from one source: HTML in the
browser, and Markdown for tools that request it. Per-tool references add a
machine-readable command catalog.

```bash
curl -H 'Accept: text/markdown' https://cmdhub.run/documentation/manual/
open https://cmdhub.run/cli/gmail/index.md
open https://cmdhub.run/cli/gmail/catalog.json
open https://cmdhub.run/llms-full.txt
```