alloy-runtime-cli
Terminal client for Alloy Runtime.
Install
pip install alloy-runtime-cli
For isolated user installs, pipx is also a good fit:
pipx install alloy-runtime-cli
Command
The installed command is alloy.
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"
Inference providers are read live from the server model catalog (GET /api/v1/models/providers), so any synced provider is valid for alloy credentials create --type org_provider --provider <key>; --kind tools and --kind mappings work offline.
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:
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:
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.
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.
Pipeline hosted runtime updates
Use alloy pipelines update to change the stored sandbox defaults for future hosted pipeline attempts:
alloy pipelines update <pipeline_id> --memory-mb 4096
alloy pipelines update <pipeline_id> --memory-mb 4096 --cpu 2 --timeout-seconds 21600
alloy pipelines update <pipeline_id> --clear-hosted-runtime-config
Runtime flags are partial updates: omitted --memory-mb, --cpu, or --timeout-seconds values stay unchanged. --clear-hosted-runtime-config removes all stored hosted runtime overrides and cannot be combined with runtime value flags.
Cancel a pending or running hosted pipeline execution with:
alloy pipelines executions cancel <pipeline_id> <execution_id>
alloy pipelines executions cancel <pipeline_id> <execution_id> --wait --timeout 120
--wait polls Alloy's persisted execution status until it is terminal. Provider
process termination remains a server-side best-effort operation.
Rerun a failed, timed-out, cancelled, or approval-waiting hosted execution with:
alloy pipelines executions rerun <pipeline_id> <execution_id>
alloy pipelines executions rerun <pipeline_id> <execution_id> --timeout 1800
alloy pipelines executions get <pipeline_id> <execution_id>
alloy pipelines executions get <pipeline_id> <execution_id> --watch
alloy pipelines executions get <pipeline_id> <execution_id> --watch --timeout 600
pipelines executions get --watch polls the aggregate pipeline live-state endpoint and renders a compact current-state view for active child generations. JSON output emits the raw live-state DTO. Regular pipelines executions get remains the durable detail surface for result data, stdout/stderr, failure context, and generation-step diagnostics.
rerun submits a new hosted attempt asynchronously and returns the queued execution state immediately. Poll get when you want the terminal result.
To regenerate exactly one terminal ctx.generate_text(step_id="...") child on the
next rerun while preserving other completed step cache hits, reset that step first:
alloy pipelines executions reset-step <pipeline_id> <execution_id> --step-id draft
alloy pipelines executions rerun <pipeline_id> <execution_id>
reset-step is parent-scoped and server-owned. It preserves the child generation
row, retires only the exact deterministic key for the requested step, and is
idempotent if the step was already reset.
Configuration
The CLI reads configuration in this order:
- CLI flags such as
--api-urland--api-key - Environment variables like
ALLOY_RUNTIME_API_URL - 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.
Model options and header display
Agent create/update/get output displays complete default_model_options maps instead of compacting to a few common keys. On agents update, use --clear-default-model-options to clear persisted defaults to null, or --default-model-options '{}' to replace them with an empty object. Header defaults are displayed with redacted values because server read surfaces never return raw default_extra_headers. alloy models list shows the copyable canonical <provider>/<model> identity in the Model column.
Hard-cut API migration
CLI automation should use canonical --model <provider>/<model>, --model-options, and --extra-headers, and should parse the canonical model field from JSON output. Legacy fallback-chain and requested/actual model output assumptions are removed. See docs/generate/hardcut_migration.md.
1 maintainer
Metadata
1 maintainer
Release files for alloy-runtime-cli 0.2.124
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| alloy_runtime_cli-0.2.124.tar.gz | 312.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| alloy_runtime_cli-0.2.124-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 816.8 kB
Release files / alloy_runtime_cli-0.2.124.tar.gz
| Download URL | alloy_runtime_cli-0.2.124.tar.gz |
|---|---|
| Size | 312.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c30dbaf07c57f7aaf4200c777386135ff6b07febc4e30f40f46d8b49327da19b
|
|
BLAKE2b-256 checksum How to use checksums |
e1cc341218dc57e701f8626ca407c8ef87336d00c39d33625d73aab94f3657dd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logRelease files / alloy_runtime_cli-0.2.124-py3-none-any.whl
| Download URL | alloy_runtime_cli-0.2.124-py3-none-any.whl |
|---|---|
| Size | 504.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
84fba8e435b553717fa8d2784cd754a8da141ddcfea324b6e50e23ed57ee4b04
|
|
BLAKE2b-256 checksum How to use checksums |
7cbe626215bdeb2dca7f5bedde3060051f761095d6d6a7f74645f181c19cd515
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency log
