agnara-cli

Project introspection and scaffolding CLI. Owns project/app generators, templates and diagnostics.

This distribution is built and versioned with the synchronized workspace set. Which versions exist on an index is answered by its PyPI project page, not by this file: a README ships inside the artifact and cannot describe the state of a publication that happens after it is built.

It installs the agnara console script.

• Import package: agnara_cli
• Depends on: the exact synchronized agnara version
• Must not import: sibling adapter packages

See ARCHITECTURE.md sections 3 and 4 for the package boundaries and the allowed dependency graph.

Status

agnara project create, agnara app create with its app-api, app-mcp, app-agent and app-worker profile shorthands, agnara apps, agnara inspect, agnara graph, agnara schema openapi and agnara context are implemented. agnara doctor remains ahead in the backlog.

agnara --help lists the commands the installed version actually has, which is the answer to trust over any list written down elsewhere.

agnara inspect

agnara inspect billing.bootstrap:app --dependencies registry
agnara inspect billing.bootstrap:app --json

Imports a compiled application and presents its filtered protocol-neutral introspection snapshot. Text and --json build one snapshot and apply one visibility decision, so the two cannot disagree, and neither derives anything from OpenAPI.

Importing the target executes the module that defines it. A malformed target is rejected before any import happens.

The attribute may be a dotted path, so an application held inside a container or a factory result needs no rearranging to be inspectable:

agnara inspect billing.bootstrap:container.app --dependencies container.registry

--visibility selects full (default), agent or identity; --as-scope simulates a viewer's scopes; --hide removes named capabilities. Offline inspection is therefore not a documented bypass of a publication decision.

Exit codes are 0 for an answer, 1 for a target the CLI could not use and 2 for an invalid command line. Output carries no ANSI decoration. See ADR 0047 and docs/CLI_SPEC.md.

agnara graph

agnara graph billing.bootstrap:app --dependencies registry

Draws capability, dependency and provider relationships from the same filtered snapshot, with the same target and visibility arguments. There is no second discovery path: both commands read one View, so neither can show something the other withheld. A withheld relationship source is named rather than drawn as an empty tree. See ADR 0048.

agnara schema openapi

agnara schema openapi billing.bootstrap:served
agnara schema openapi billing.bootstrap:document --output openapi.json

Exports the OpenAPI document the composition produced. This package must not import agnara-http, so it does not project one — which is also the safer design: a second projection here could disagree with the one a server serves.

The named attribute may be serialized bytes, the mapping they came from, or a zero-argument callable returning either. Bytes are emitted unchanged, so an export is byte-identical to what is served. --output writes a file and refuses to replace one without --overwrite. See ADR 0050.

agnara context

agnara context billing.bootstrap:app --visibility agent
agnara context billing.bootstrap:app --output CAPABILITIES.md

Renders the filtered snapshot as Markdown for a model to read, from the same shared view agnara inspect uses. Every rendering states that seeing a capability is not permission to invoke it, and a withheld field is named rather than printed as its declared default. Not llms.txt, and not a security boundary. See ADR 0051.