Metadata-Version: 2.4
Name: alloy-runtime-cli
Version: 0.2.82
Summary: Alloy Runtime CLI - Command-line interface for Alloy Runtime server
Keywords: alloy,cli,python,terminal,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: typer==0.24.1
Requires-Dist: rich==15.0.0
Requires-Dist: textual==8.2.3
Requires-Dist: genson==1.3.0
Requires-Dist: pyperclip==1.11.0
Requires-Dist: prompt-toolkit==3.0.52
Requires-Dist: alloy-runtime-sdk==0.2.82
Requires-Dist: alloy-runtime-types==0.2.82
Requires-Dist: trogon==0.6.0

# alloy-runtime-cli

Terminal client for Alloy Runtime.

## Install

```bash
pip install alloy-runtime-cli
```

For isolated user installs, `pipx` is also a good fit:

```bash
pipx install alloy-runtime-cli
```

## Command

The installed command is `alloy`.

```bash
alloy --help
alloy --help-json
alloy --help-markdown
alloy --help-toon
alloy --format table pipelines list
alloy --format json agents list
alloy login
alloy credentials supported
alloy credentials supported --kind tools
alloy --api-url https://your-alloy-runtime-host ping
alloy api-keys create --scope read --scope update --scope use --description "automation key"
```

Use `alloy --help-json` when automation or agents need recursive machine-readable CLI help as JSON.
Use `alloy --help-markdown` for the same help tree rendered as Markdown.
Use `alloy --help-toon` for the same help tree rendered as TOON.
For session-wide help rendering, set `ALLOY_RUNTIME_HELP_FORMAT=json`, `ALLOY_RUNTIME_HELP_FORMAT=markdown`, or `ALLOY_RUNTIME_HELP_FORMAT=toon` and run `alloy --help`.

For scoped create commands such as `agents create`, `schemas create`, `tool-configs create`, and `templates create`, the CLI now defaults omitted ownership scope to **organization**. Pass `--scope user` only when you want a personal resource.

Use `alloy --format compact` for the existing psql-style human-readable record view.
Use `alloy --format table` for Rich table output in the non-TUI CLI.
Use `alloy --format json` for automation-friendly machine-readable output.

Running `alloy` without a subcommand launches the Textual TUI. TUI chat uses the
standard non-streaming generation path, so it works with agents that have tools
configured. Responses appear once the full turn completes rather than token-by-token.

For live model-execution inspection, use:

```bash
alloy executions get <execution_id>
alloy executions get <execution_id> --watch
alloy executions get <execution_id> --full-output
```

`alloy executions get` uses a dedicated transcript view for human output: one metadata header followed by chronological reasoning, grouped tool-call/result, and assistant blocks. Tool inputs are always complete; tool outputs are compact by default, and `--full-output` expands them. RAG retrieval diagnostics are printed above `rag_search` tool output bodies, with failures highlighted red and degraded retrieval highlighted yellow. `--watch` repaints a live grouped snapshot while the execution is still running and waits indefinitely unless you pass `--timeout <seconds>`.

For piping-friendly access to the latest assistant response in a chat session,
including structured responses emitted as formatted JSON, use:

```bash
alloy sessions last <session_id>
alloy sessions last <session_id> -o clipboard
alloy sessions last <session_id> -o file -O response.md
```

`alloy generate status <execution_id>` displays the session ID when one exists,
so you can move from an execution to the session response without parsing a full
transcript.

`alloy ping` is the authenticated connectivity check. It confirms who you are, which host you reached, and which server build answered the request.

The CLI pins `toon-format` from the upstream GitHub source because the PyPI stub release is not usable yet.

## Template validation

Use `alloy templates validate` when you want to check local Jinja content against the server's template resolution and helper validation rules before saving anything.

```bash
alloy templates validate --file ./templates/email.jinja2 --var user.name=Alice
alloy templates validate --content "Hello {{ name }}" --var name=World
```

Use `templates validate` for local drafts and CI-style checks. Use `templates create` or `templates update` when you want to persist the template after it passes validation.
The command prints validation details either way and exits non-zero when the template is not renderable with the supplied variables.

## Configuration

The CLI reads configuration in this order:

1. CLI flags such as `--api-url` and `--api-key`
2. Environment variables like `ALLOY_RUNTIME_API_URL`
3. Stored credentials in `~/.alloy-runtime/config`

Use `alloy login` to save an API key locally, or set the environment variables when
running on a VPS.

CLI release trigger: no functional changes.
