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
jsonandjsonloutput 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 loginsigns 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--jsonin scripts) is the health check for a tool.gmail auth whoamiconfirms which account you are about to act as.- Profiles are explicit. Pass
--profile workwhen 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:
- Confirm the account with
auth status. - Confirm the target with a
list,search,get, orresolvecommand. - Check the input fields with
schema <target> --inputwhen available. - Prefer an explicit identifier, short ref, or piped record over free text.
- Use
--dry-runwhen 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