# cmdhub CLI

Control plane for install, auth, provider links, config, and suite health.

## Install

```bash
curl -fsSL https://cmdhub.run/install.sh | bash
```

## Authentication

cmdhub account

## Agent-Readable Catalog

- Machine-readable command catalog: `/cli/cmdhub/catalog.json`
- Stable command anchors use the `cmd-...` IDs listed under each command.
- Inspect this catalog before planning tool use for command paths, examples, flags, mutation markers, and dry-run support.

## Overview

```bash
# Install the current suite, then inspect what is available
cmdhub auth login
cmdhub get gmail gcal gdrive mscal msdrive mstodo msoutlook slack notion agent
cmdhub list
```

## CLI Overview

Cmdhub control plane for the CLI suite

Manage the cmdhub suite: install tools, inspect tool metadata, and run suite diagnostics.

Cmdhub is the control plane. App CLIs such as gmail, gcal, slack, notion, and agent remain the data plane.

## Generated Coverage

- Command groups: `18`
- Total documented command nodes: `29`
- Live examples: `5`
- Lifecycle surfaces: `auth`, `doctor`, `capabilities`, `schema`, `version`
- Machine-readable output: `--json`, `--jsonl`
- Human views: `summary`, `full`

## Auth Contract

- Auth mode: cmdhub account
- Provider permission model: cmdhub account session
- Auth scopes: `cmdhub registry/account session`
- Scope note: Website account auth does not grant provider API access.
- Standard commands: `auth login`, `auth logout`, `auth status`, `auth whoami`
- `auth status --json` reports `tool`, `profile`, `provider`, `authenticated`, and `suggested_next_step`.
- `auth whoami --json` is the stable way to answer identity questions.

## Agent Safety Notes

- Discovery commands such as `list`, `search`, `get`, `resolve`, `schema`, `doctor`, `capabilities`, `status`, and `whoami` are the safest commands to run first.
- Treat commands marked as mutating as state-changing local or provider operations.
- Mutating command paths: `cmdhub auth login`, `cmdhub auth logout`, `cmdhub config set`, `cmdhub login`, `cmdhub logout`, `cmdhub pin`, `cmdhub remove`, `cmdhub unpin`, `cmdhub update`
- No generated `--dry-run` flag was detected for this CLI. Use discovery commands before mutating commands.

## Global Flags

- `--json` (bool): Emit JSON machine output
- `--jsonl` (bool): Emit JSONL records for piping
- `--output` (string): Compatibility output mode: json|jsonl. Prefer --json or --jsonl
- `--view` (string): View mode: summary|full Default: `summary`.
- `--profile` (string): Config/auth profile
- `--config` (string): Config path override
- `--quiet` (bool): Suppress non-essential diagnostics
- `--debug` (bool): Enable debug diagnostics
- `--limit` (int): Maximum items to emit Default: `50`.
- `--page-size` (int): Requested upstream page size Default: `50`.
- `--cursor` (string): Continuation cursor
- `--no-paginate` (bool): Fetch only one page
- `--version` (bool): Print version information

## Command Reference

### `cmdhub auth`

- Anchor: `cmd-cmdhub-auth`
- Mutates state: `no`
- Supports dry run: `no`

Manage cmdhub account authentication

Manage the local cmdhub account session. Login opens the cmdhub web auth page and stores the resulting hub session.

Example:

```bash
cmdhub auth login
  cmdhub auth status
  cmdhub auth whoami
  cmdhub auth logout
```

#### `cmdhub auth login`

- Anchor: `cmd-cmdhub-auth-login`
- Mutates state: `yes`
- Supports dry run: `no`

Start browser login for cmdhub

Example:

```bash
cmdhub auth login
cmdhub auth login --help
cmdhub auth login --token <token> --email you@example.com
```

Flags:

- `--email` (string): Account email for manual bootstrap
- `--host` (string): Cmdhub web auth host Default: `https://cmdhub.run`.
- `--name` (string): Display name for manual bootstrap
- `--timeout` (duration): How long to wait for browser login Default: `2m0s`.
- `--token` (string): Manual bootstrap session token
- `--user-id` (string): User identifier for manual bootstrap

#### `cmdhub auth logout`

- Anchor: `cmd-cmdhub-auth-logout`
- Mutates state: `yes`
- Supports dry run: `no`

Clear cmdhub auth state

Example:

```bash
cmdhub auth logout
cmdhub auth logout --help
```

#### `cmdhub auth status`

- Anchor: `cmd-cmdhub-auth-status`
- Mutates state: `no`
- Supports dry run: `no`

Show cmdhub auth status

Example:

```bash
cmdhub auth status
cmdhub auth status --view full
```

#### `cmdhub auth whoami`

- Anchor: `cmd-cmdhub-auth-whoami`
- Mutates state: `no`
- Supports dry run: `no`

Show the current cmdhub account

Example:

```bash
cmdhub auth whoami
```

### `cmdhub capabilities`

- Anchor: `cmd-cmdhub-capabilities`
- Mutates state: `no`
- Supports dry run: `no`

Show tool capabilities

Example:

```bash
cmdhub capabilities
cmdhub capabilities --json
cmdhub capabilities gmail
cmdhub capabilities gmail --json
```

### `cmdhub config`

- Anchor: `cmd-cmdhub-config`
- Mutates state: `no`
- Supports dry run: `no`

Manage shared cmdhub config

Example:

```bash
cmdhub config get
  cmdhub config get credential_backend
  cmdhub config set credential_backend auto
```

#### `cmdhub config get`

- Anchor: `cmd-cmdhub-config-get`
- Mutates state: `no`
- Supports dry run: `no`

Get config values

Example:

```bash
cmdhub config get
cmdhub config get credential_backend
cmdhub config get credential_backend --json
```

#### `cmdhub config set`

- Anchor: `cmd-cmdhub-config-set`
- Mutates state: `yes`
- Supports dry run: `no`

Set a config value

Example:

```bash
cmdhub config set --help
cmdhub config set credential_backend auto
cmdhub config set docs_open_command xdg-open
```

### `cmdhub doctor`

- Anchor: `cmd-cmdhub-doctor`
- Mutates state: `no`
- Supports dry run: `no`

Run suite diagnostics

Example:

```bash
cmdhub doctor
cmdhub doctor --view full
cmdhub doctor gmail
```

### `cmdhub get`

- Anchor: `cmd-cmdhub-get`
- Mutates state: `no`
- Supports dry run: `no`

Install one or more tools

Example:

```bash
cmdhub get --help
cmdhub get gmail
cmdhub get gmail gcal slack
cmdhub get gmail gcal slack notion
cmdhub get gmail@0.4.0
```

### `cmdhub info`

- Anchor: `cmd-cmdhub-info`
- Mutates state: `no`
- Supports dry run: `no`

Show metadata for one tool

Example:

```bash
cmdhub info
cmdhub info gmail
cmdhub info gmail --json
cmdhub info gmail --view full
```

### `cmdhub installed`

- Anchor: `cmd-cmdhub-installed`
- Mutates state: `no`
- Supports dry run: `no`

List installed tools

Example:

```bash
cmdhub installed
cmdhub installed --view full
```

### `cmdhub list`

- Anchor: `cmd-cmdhub-list`
- Mutates state: `no`
- Supports dry run: `no`

List known tools

Example:

```bash
cmdhub list
cmdhub list --jsonl
cmdhub list --view full
```

### `cmdhub login`

- Anchor: `cmd-cmdhub-login`
- Mutates state: `yes`
- Supports dry run: `no`

Start browser login for cmdhub

Example:

```bash
cmdhub auth login
cmdhub login
cmdhub login --token <token> --email you@example.com
```

Flags:

- `--email` (string): Account email for manual bootstrap
- `--host` (string): Cmdhub web auth host Default: `https://cmdhub.run`.
- `--name` (string): Display name for manual bootstrap
- `--timeout` (duration): How long to wait for browser login Default: `2m0s`.
- `--token` (string): Manual bootstrap session token
- `--user-id` (string): User identifier for manual bootstrap

### `cmdhub logout`

- Anchor: `cmd-cmdhub-logout`
- Mutates state: `yes`
- Supports dry run: `no`

Clear cmdhub auth state

Example:

```bash
cmdhub auth logout
cmdhub logout
```

### `cmdhub pin`

- Anchor: `cmd-cmdhub-pin`
- Mutates state: `yes`
- Supports dry run: `no`

Pin an installed tool to a version

Example:

```bash
cmdhub pin --help
cmdhub pin gmail
cmdhub pin gmail@0.4.0
```

### `cmdhub remove`

- Anchor: `cmd-cmdhub-remove`
- Mutates state: `yes`
- Supports dry run: `no`

Remove installed tools

Example:

```bash
cmdhub remove --help
cmdhub remove gmail
cmdhub remove gmail gcal
```

### `cmdhub schema`

- Anchor: `cmd-cmdhub-schema`
- Mutates state: `no`
- Supports dry run: `no`

Show a tool command schema when supported

Example:

```bash
cmdhub schema
cmdhub schema cmdhub tool.list --out
cmdhub schema gmail message.create --in
cmdhub schema gmail message.get --out
```

Flags:

- `--in` (bool): Show input schema
- `--out` (bool): Show output schema

### `cmdhub telemetry`

- Anchor: `cmd-cmdhub-telemetry`
- Mutates state: `no`
- Supports dry run: `no`

Manage anonymous cmdhub telemetry

Example:

```bash
cmdhub telemetry status
  cmdhub telemetry disable
  cmdhub telemetry flush
```

#### `cmdhub telemetry disable`

- Anchor: `cmd-cmdhub-telemetry-disable`
- Mutates state: `no`
- Supports dry run: `no`

Disable anonymous telemetry

Example:

```bash
cmdhub telemetry disable
cmdhub telemetry disable --help
```

#### `cmdhub telemetry enable`

- Anchor: `cmd-cmdhub-telemetry-enable`
- Mutates state: `no`
- Supports dry run: `no`

Enable anonymous telemetry

Example:

```bash
cmdhub telemetry enable
cmdhub telemetry enable --help
```

#### `cmdhub telemetry flush`

- Anchor: `cmd-cmdhub-telemetry-flush`
- Mutates state: `no`
- Supports dry run: `no`

Upload queued telemetry now

Example:

```bash
cmdhub telemetry flush
cmdhub telemetry flush --help
```

#### `cmdhub telemetry path`

- Anchor: `cmd-cmdhub-telemetry-path`
- Mutates state: `no`
- Supports dry run: `no`

Show the local telemetry queue path

Example:

```bash
cmdhub telemetry path
```

#### `cmdhub telemetry status`

- Anchor: `cmd-cmdhub-telemetry-status`
- Mutates state: `no`
- Supports dry run: `no`

Show telemetry status

Example:

```bash
cmdhub telemetry status
cmdhub telemetry status --json
```

### `cmdhub unpin`

- Anchor: `cmd-cmdhub-unpin`
- Mutates state: `yes`
- Supports dry run: `no`

Clear a version pin on an installed tool

Example:

```bash
cmdhub unpin --help
cmdhub unpin gmail
```

### `cmdhub update`

- Anchor: `cmd-cmdhub-update`
- Mutates state: `yes`
- Supports dry run: `no`

Update installed tools

Preview updates for installed tools. Rerun with --yes to apply. Pinned tools are held back.

Example:

```bash
cmdhub update
cmdhub update --all
cmdhub update --help
cmdhub update all
cmdhub update gmail --yes
```

Flags:

- `--all` (bool): Plan updates for every installed tool (default if no targets are given)
- `--yes` (bool): Apply the planned updates

### `cmdhub version`

- Anchor: `cmd-cmdhub-version`
- Mutates state: `no`
- Supports dry run: `no`

Show cmdhub version information

Example:

```bash
cmdhub version
cmdhub version --json
```

### `cmdhub whoami`

- Anchor: `cmd-cmdhub-whoami`
- Mutates state: `no`
- Supports dry run: `no`

Show the current cmdhub account

Example:

```bash
cmdhub whoami
```

## Live Examples

### Lifecycle

#### Show root help

Shows installed command families and global usage.

_Example metadata: provider state: local._

```bash
cmdhub --help
```

```text
Manage the cmdhub suite: install tools, inspect tool metadata, and run suite diagnostics.

Cmdhub is the control plane. App CLIs such as gmail, gcal, slack, notion, and agent remain the data plane.

Usage:
  cmdhub [command]

Examples:
  cmdhub auth login
  cmdhub list
  cmdhub get gmail gcal
  gmail login
  cmdhub doctor
  cmdhub schema gmail message.get --out

Available Commands:
  auth         Manage cmdhub account authentication
  capabilities Show tool capabilities
  completion   Generate the autocompletion script for the specified shell
  config       Manage shared cmdhub config
  doctor       Run suite diagnostics
  get          Install one or more tools
  help         Help about any command
  info         Show metadata for one tool
  installed    List installed tools
  list         List known tools
  login        Start browser login for cmdhub
  logout       Clear cmdhub auth state
  pin          Pin an installed tool to a version
  remove       Remove installed tools
  schema       Show a tool command schema when supported
  telemetry    Manage anonymous cmdhub telemetry
  unpin        Clear a version pin on an installed tool
  update       Update installed tools
  version      Show cmdhub version information
  whoami       Show the current cmdhub account

Flags:
      --config string   Config path override
      --cursor string   Continuation cursor
      --debug           Enable debug diagnostics
  -h, --help            help for cmdhub
      --json            Emit JSON machine output
      --jsonl           Emit JSONL records for piping
      --limit int       Maximum items to emit (default 50)
      --no-paginate     Fetch only one page
  -o, --output string   Compatibility output mode: json|jsonl. Prefer --json or --jsonl
      --page-size int   Requested upstream page size (default 50)
  -q, --quiet           Suppress non-essential diagnostics
  -v, --version         Print version information
      --view string     View mode: summary|full (default "summary")

Use "cmdhub [command] --help" for more information about a command.
```

#### Inspect available tools

Lists known tools, install state, auth mode, and machine-output support.

_Example metadata: provider state: local._

```bash
cmdhub list
```

```text
TOOL         VERSION      STATUS           AUTH           SCHEMA  JSONL
cmdhub       dev          update available session        yes     yes  
gcal         0.0.3        not installed    oauth          yes     yes  
gmail        0.0.5        not installed    oauth          yes     yes  
signal       0.0.1        not installed    device_link    yes     yes  
slack        0.0.3        not installed    oauth          yes     yes  

Next steps:
- Run:       cmdhub get gcal
- Installed: cmdhub installed
- Update:    cmdhub update
```

#### Show version

Prints cmdhub build metadata.

_Example metadata: provider state: local._

```bash
cmdhub version
```

```text
cmdhub dev

Next steps:
- Doctor: cmdhub doctor
- List:   cmdhub list
```

### Diagnostics

#### Show telemetry status

Shows anonymous telemetry status.

_Example metadata: provider state: local._

```bash
cmdhub telemetry status
```

```text
Telemetry: disabled
Pending:   {count}

Next steps:
- Flush:  cmdhub telemetry flush
- Enable: cmdhub telemetry enable
```

### Schemas

#### Inspect a command schema

Shows a command output schema without needing provider auth.

_Example metadata: provider state: local._

```bash
cmdhub schema cmdhub tool.list --out
```

```text
Schema: cmdhub.tool.list.v1.output (cmdhub tool list output)
Required: name, latest_version, status
Optional: display_name, auth_mode, installed, installed_version, command_schema, jsonl
Fields:
  auth_mode          Authentication mode
  name               Tool command name
  status             Install/update state
```