octo-cli: Instructions file for Claude Code

CLAUDE.md — octo-cli project instructions

What is octo-cli

octo-cli is the command-line interface for the Octo ecosystem, built for AI Agent Bots to call via exec from agent runtimes (OpenClaw, Claude Code, etc.). Output is a JSON envelope; agent-runtime commands take no interactive I/O. The sole exception is octo-cli auth login, an operator-only setup step that reads the token from a hidden terminal prompt (or stdin).

Architecture

• Go single binary, cobra CLI framework.
• Metadata-driven: the entire service command tree is auto-registered at startup from OpenAPI 3.x specs embedded into the binary via internal/registry. To add or change an endpoint, update a spec — not code. Spec extensions cover identity routing (x-octo-allowed-token-kinds, x-octo-mount-by-token-kind), output shaping (x-octo-response-fields, x-octo-lossless-id-fields), and log hygiene (x-octo-secret); each is opt-in, and omitting it keeps the historical behaviour byte-for-byte. x-octo-flag renames the flag for a query/header param or a promoted body field, and on a path param it adds an optional flag alternative to the positional slot (the escape hatch for base64url ids starting with -, which cobra would parse as a flag) — an operation with no such declaration keeps cobra.ExactArgs.
• Thin client: all business logic lives in backend services (matters, dmworkim). CLI is transport + validation + formatting.
• Unified gateway: every domain uses OCTO_API_BASE_URL; embedded OpenAPI paths carry module namespaces such as /market/api, /docs-html, and /fleet/api.
• Factory DI: internal/cmdutil.Factory is the DI container; no package-level globals. Tests inject stubs through ConfigFunc / CredentialFunc / ClientFunc / RegistryFunc. Factory.ErrorEmitted tracks whether an error envelope was already written to stderr, preventing double-emit between RunE and the top-level main error handler.
• JSON envelope I/O: {ok, identity, data, _pagination, _rate_limit} on stdout for success; {ok:false, error:{type,code,message,hint,detail}} on stderr for failure. Exit codes: auth=3, validation/config=2, rest=1.
• Pre-flight validation (cmd/service/run.go, cmd/service/enum.go): the metadata-driven path checks the resolved request against the spec before any HTTP — required fields and minItems (VALIDATION_ERROR), spec enum vocabularies (ENUM_NOT_ALLOWED), uint64 id range, and a refusal of empty or . / .. path values (an empty value addresses the collection and a gateway that normalises dot segments retargets the request — and the engine emits DELETE). Loop Public API operations and services or operations that opt into x-octo-strict-request-schema (Marketplace service and selected group-update, Docs attachment, PPT, sheet and sharing operations) additionally enforce composition, closed-object and minimum-property constraints, Unicode string lengths and maximum array sizes; those extended checks remain backend-enforced for other legacy domains. Body checks walk the merged body, so --data is validated too, at every nesting depth and including format: uint64 — --data is not a raw passthrough on this path, and it decodes with UseNumber so an id above 2^53 is never rounded before it is checked. A property present with an explicit null is checked, not skipped: an enum admits it only when JSON null is an explicit member, and a uint64 format admits it only when the schema's OpenAPI 3.1 type union explicitly includes null. This preserves optional search-filter boundaries while refusing parent_id:null: a non-nullable scalar id would decode as folder 0, the documented root, i.e. a valid id addressing a place nobody named. A required field set to null is reported as missing instead, so both paths refuse it; a null on an unconstrained property is still forwarded, since a backend may accept it to clear the field. Enum and constant comparison is by canonical form, not ==, because the same wire value arrives as int, float64 or json.Number depending on how it was supplied; numbers compare by exact decimal text, so an integer vocabulary admits 1 but not 1.0 — the body keeps what the caller wrote, and a non-integer would fail at the backend on a value the local gate had called valid. Hand-written composites reuse the same walker via service.ValidateRequestBody, so a composite that replaces a generated leaf cannot enforce a weaker contract than the leaf did.
• Schema-level x-octo-enum-hint appends actionable guidance to ENUM_NOT_ALLOWED. It survives allOf merging: an outer hint wins, otherwise the first nonempty inherited hint wins. Other enum validation semantics are unchanged.