commands catalog¶

NAME¶

phyware commands catalog — emit a machine-readable catalog of every phyware command.

SYNOPSIS¶

phyware commands catalog [OPTIONS]

DESCRIPTION¶

Outputs a structured, versioned catalog of all phyware commands, including their options, arguments, JSON schemas, examples, and agent notes. Designed for consumption by AI agents and automation tooling.

The catalog validates against the JSON Schema at docs-site/docs/phyware/catalog-schema.json.

OPTIONS¶

Flag	Type	Required	Default	Env
`--output`	`json/yaml/tsv`	No	`json`	—

ARGUMENTS¶

None.

INPUT¶

None.

OUTPUT¶

A CommandCatalog object with:

Field	Type	Description
`$schema`	string	JSON Schema URI
`version`	string	Catalog schema version
`cli`	string	CLI name (`phyware`)
`description`	string	Catalog description
`commands`	array	Array of `CommandDescriptor` objects

Each CommandDescriptor has: name, group, synopsis, description, options, arguments, input_schema, output_schema, exit_codes, examples, agent_notes, see_also, errors.

EXIT CODES¶

Code	Meaning
`0`	Success
`1`	Generic / connection error
`2`	Authentication / authorisation error
`3`	Resource not found
`4`	Validation error
`5`	Server-side error

EXAMPLES¶

# Emit catalog as JSON (default)
phyware commands catalog

# Emit as YAML
phyware commands catalog --output yaml

# List command names and synopses (TSV)
phyware commands catalog --output tsv

# Extract all command names with jq
phyware commands catalog | jq '[.commands[].name]'

# Find commands in the cloud group
phyware commands catalog | jq '[.commands[] | select(.group == "cloud") | .name]'

AGENT NOTES¶

This command is the primary entry point for AI agents to discover the full phyware CLI surface. Fetch the catalog once at the start of a session and cache it. Use agent_notes fields within each descriptor for usage guidance. No authentication required.

ERRORS¶

Code	Message	Remediation
`INTERNAL`	Serialization error	File a bug report