Metadata-Version: 2.5
Name: agnara-cli
Version: 1.0.3
Summary: Project introspection and scaffolding CLI for Agnara.
Project-URL: Homepage, https://github.com/Blandskron/agnara
Project-URL: Repository, https://github.com/Blandskron/agnara
Author-email: Agnara Maintainers <maintainers@agnara.dev>
License: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.14
Requires-Dist: agnara==1.0.3
Description-Content-Type: text/markdown

# agnara-cli

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

```bash
pip install "agnara-cli==1.0.3"
agnara --help
```

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.
The governed Python exports are listed in
[`docs/API_REFERENCE.md`](../../docs/API_REFERENCE.md); generated projects use
the governed kernel imports. Importing a project target executes that module.

- 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`

```bash
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:

```bash
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`

```bash
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`

```bash
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`

```bash
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.
