Agent Manual

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

New here? Start with Getting Started 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:

gmail message list --inbox --limit 5

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

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:

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:

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:

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:

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.

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