alloy-runtime-cli 0.2.109

Alloy Runtime CLI - Command-line interface for Alloy Runtime server

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"

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:

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.

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.