Overview

Operator CLI

The phrony binary is the operator CLI for a running Phrony runtime. It speaks gRPC to phrony-runtime for publish, deploy, sessions, and agent lifecycle. It also validates manifests locally without contacting the server.

The lifecycle in plain terms

An agent goes through the same short journey every time, and most commands map to one step of it:

1. Author & check (on your machine)

   Write the manifest, then validate it. Nothing leaves your laptop yet.

   Shell

   Copy

   $ phrony init ./weather-assistant
   $ phrony agents validate ./weather-assistant/agent.yaml

2. Publish (freeze a version)

   publish sends a version to the runtime and freezes it forever. Publishing does not make it live — it's a version sitting in the library, ready but not in use.

   Shell

   Copy

   $ export ANTHROPIC_API_KEY="sk-..."
   $ phrony agents publish ./weather-assistant/agent.yaml
   # → weather/weather-assistant 2.4.0 stored (not runnable until deploy)

3. Deploy (make one version live)

   deploy flips a switch: this published version is now the active one that new runs will use. rollback flips it back to an earlier version.

   Shell

   Copy

   $ phrony agents deploy weather/weather-assistant@2.4.0
   $ phrony rollback weather/weather-assistant # optional: back to previous active

4. Run (execute the live version)

   run starts a session — one execution of the agent — against whatever version is currently active.

   Shell

   Copy

   $ phrony run weather/weather-assistant
   # → run_abc123 started (uses active 2.4.0)

Why separate "publish" from "deploy"? So you can stage a new version safely and switch to it (or away from it) instantly, without re-uploading anything — the same reason deployments are separated from builds elsewhere in software.

Install

From a runtime repository checkout:

$ make install-cli-path

Or build and place on your PATH manually — see Install binaries.

Connect to the runtime

The CLI resolves the runtime address in this order:

1. --runtime-addr on the command line
2. PHRONY_RUNTIME_ADDR in the environment
3. Default 127.0.0.1:7777

$ phrony --runtime-addr 127.0.0.1:7777 status

Load .env from the runtime repo (or set PHRONY_RUNTIME_ADDR) so the CLI matches RUNTIME_GRPC_ADDR where the daemon listens.

Agent references

Commands that take an agent use namespace/name:

demo/echo-agent

Versioned references use namespace/name@semver (for example demo/echo-agent@1.2.0). The semver comes from metadata.version in the published manifest.

Agent lifecycle

Within one runtime instance, an agent version moves through distinct steps:

flowchart LR
  yaml[agent.yaml] -->|validate| ok[valid]
  ok -->|publish| ver["published version\n(immutable)"]
  ver -->|deploy| act["active deployment"]
  act -->|run| sess[session]
  act -->|rollback| act

Publish validates the bundle, resolves refs, and stores an immutable agent version (ref-only secrets when declared). Deploy appends an activation record so that version becomes the active one for run. Run resolves secret values per session when needed. Published-but-not-deployed versions exist in the registry but cannot be executed.

Bare phrony run demo/echo-agent resolves the active deployed version. An explicit demo/echo-agent@1.2.0 is allowed only when 1.2.0 is the currently active deployment in this runtime.

Each runtime instance is environment-agnostic: promoting between staging and production means publishing and deploying on separate runtime instances (typically via CI/CD), not a target or promote flag on the CLI.

Audit actor

Publish, deploy, and rollback record an actor for audit. Set PHRONY_ACTOR on the operator host (for example ci@github or an email). When unset, the CLI uses the OS username.

Commands

Agent commands (agents)

Bundle commands (bundles)

Multi-agent closures use kind: Bundle. See bundles for the full command reference.

Global flags

Typical workflow

$ phrony init ./my-agent
$ phrony agents validate ./my-agent/agent.yaml
$ phrony agents publish ./my-agent/agent.yaml
$ phrony agents deploy demo/my-agent@0.1.0
$ export ANTHROPIC_API_KEY="sk-..." # or: phrony run demo/my-agent -e .env
$ phrony run demo/my-agent