CLI Tree

Both trees below are generated by ChatStyle from the real Click command registry. Tests run chatauth --tree and chatauth --tree-brief and compare their output with these fenced blocks so the documentation cannot drift away from the real command surface.

Full tree

chatauth --tree retains argument and option signatures:

chatauth
├── --help  # Show this message and exit.
├── --version  # Show the version and exit.
├── --tree  # Print the registered CLI tree and exit.
├── --tree-brief  # Print the registered CLI tree without parameter signatures and exit.
├── admin  # Local admin operations.
│   ├── clients  # OAuth client registry.
│   │   ├── create <NAME> [--state-dir STATE-DIR] [--audience AUDIENCE] [--scope SCOPES] [--execute]  # Plan an OAuth client; --execute writes it to local state.
│   │   └── list [--state-dir STATE-DIR]  # List safe OAuth client metadata without credentials.
│   ├── grants  # Refresh-token grant families.
│   │   ├── issue <CLIENT-ID> <SUBJECT> [--state-dir STATE-DIR] [--audience AUDIENCE] [--scope SCOPES] [--ttl-days TTL-DAYS] [--handoff-file HANDOFF-FILE] [--execute]  # Plan a refresh grant; --execute writes state and a private handoff file.
│   │   └── list [--state-dir STATE-DIR]  # List safe refresh-grant metadata without token values.
│   ├── keys  # Signing keys and JWKS.
│   │   ├── jwks [--state-dir STATE-DIR]  # Export public JWKS without private key material.
│   │   └── list [--state-dir STATE-DIR]  # List signing-key metadata without private key material.
│   └── subjects  # Principals that can receive refresh grants.
│       ├── create <SUBJECT> [--state-dir STATE-DIR] [--display-name DISPLAY-NAME] [--execute]  # Plan a subject; --execute writes it to local state.
│       └── list [--state-dir STATE-DIR]  # List safe subject metadata without credentials.
├── health [--state-dir STATE-DIR]  # Check local ChatAuth state health without changing it.
├── service  # Local ChatAuth service lifecycle.
│   ├── doctor [--state-dir STATE-DIR]  # Inspect local state, config, and key metadata without secrets.
│   ├── init [--state-dir STATE-DIR] [--issuer ISSUER] [--execute]  # Plan local state setup; --execute creates the database and signing key.
│   └── run  # Reserved ASGI service runner; exits non-zero in ChatAuth 0.1.x.
├── token  # Machine-side runtime token store operations.
│   ├── clear [--token-store TOKEN-STORE] [--execute]  # Plan token-store removal; --execute deletes the local store.
│   ├── import-refresh [--state-dir STATE-DIR] [--token-store TOKEN-STORE] [--from-file FROM-FILE] [--execute]  # Plan refresh-token import; --execute writes the private token store.
│   ├── refresh [--state-dir STATE-DIR] [--token-store TOKEN-STORE] [--execute]  # Plan token rotation; --execute updates the private token store.
│   └── status [--token-store TOKEN-STORE]  # Show token-store metadata without token values.
└── verify  # Resource-side verification helpers.
    ├── access-token [--state-dir STATE-DIR] [--token-store TOKEN-STORE] [--audience AUDIENCE] [--scope SCOPES] [--jwks-file JWKS-FILE] [--issuer ISSUER]  # Verify the stored access token and print only valid or invalid.
    └── jwks [--state-dir STATE-DIR]  # Export public JWKS for resource-side verification.

Brief tree

chatauth --tree-brief retains the same nodes and descriptions while omitting argument and option signatures:

chatauth
├── --help  # Show this message and exit.
├── --version  # Show the version and exit.
├── --tree  # Print the registered CLI tree and exit.
├── --tree-brief  # Print the registered CLI tree without parameter signatures and exit.
├── admin  # Local admin operations.
│   ├── clients  # OAuth client registry.
│   │   ├── create  # Plan an OAuth client; --execute writes it to local state.
│   │   └── list  # List safe OAuth client metadata without credentials.
│   ├── grants  # Refresh-token grant families.
│   │   ├── issue  # Plan a refresh grant; --execute writes state and a private handoff file.
│   │   └── list  # List safe refresh-grant metadata without token values.
│   ├── keys  # Signing keys and JWKS.
│   │   ├── jwks  # Export public JWKS without private key material.
│   │   └── list  # List signing-key metadata without private key material.
│   └── subjects  # Principals that can receive refresh grants.
│       ├── create  # Plan a subject; --execute writes it to local state.
│       └── list  # List safe subject metadata without credentials.
├── health  # Check local ChatAuth state health without changing it.
├── service  # Local ChatAuth service lifecycle.
│   ├── doctor  # Inspect local state, config, and key metadata without secrets.
│   ├── init  # Plan local state setup; --execute creates the database and signing key.
│   └── run  # Reserved ASGI service runner; exits non-zero in ChatAuth 0.1.x.
├── token  # Machine-side runtime token store operations.
│   ├── clear  # Plan token-store removal; --execute deletes the local store.
│   ├── import-refresh  # Plan refresh-token import; --execute writes the private token store.
│   ├── refresh  # Plan token rotation; --execute updates the private token store.
│   └── status  # Show token-store metadata without token values.
└── verify  # Resource-side verification helpers.
    ├── access-token  # Verify the stored access token and print only valid or invalid.
    └── jwks  # Export public JWKS for resource-side verification.

Command groups

Group	Responsibility	Mutation boundary
`health`	quick state health readback	read-only
`service`	local issuer state lifecycle	`init` requires `--execute`; `run` is reserved and exits non-zero
`admin clients`	OAuth client registry	`create` requires `--execute`
`admin subjects`	subjects that can receive refresh grants	`create` requires `--execute`
`admin grants`	refresh-token grant family	`issue` requires `--execute` and writes a handoff file
`admin keys`	signing-key metadata / JWKS	read-only
`token`	machine-side runtime token-store	import / refresh / clear require `--execute`
`verify`	resource-side JWKS and access-token verification	read-only

Interfaces not implemented yet

chatauth service run is reserved and exits non-zero in 0.1.x. It does not start an HTTP service and does not pretend the service is running. When a real ASGI/HTTP /oauth/token service is added, it should land with Python APIs, tests, quickstart updates, and deployment docs.