Valet|Docs
Sign up

CLI: Releases & Drafts

A release is a versioned, built bundle of an agent's code. A draft is an ephemeral branch forked from the agent's main HEAD — an in-progress edit that you review before publishing. valet deploy runs the whole pipeline in one shot (draft, push, publish, deploy); the drafts subcommands break it into individual steps for out-of-band edits.

List releases

valet releases [<name>] [-a <agent>] [--org <org>]

Lists the release history for an agent, newest first. The (current) marker flags the release the agent is actually running. Releases published to main but not yet deployed do not appear — only built releases do.

$ valet releases my-agent
=== Releases on my-agent
  v3    active   abc1234  2026-06-01T12:00:00Z  (current)
  v2    active   def5678  2026-05-20T09:30:00Z
  v1    active   9abcdef  2026-05-01T08:00:00Z

Inspect the deployed release

valet releases files [<name>]
valet releases read [<name>] <path>

files lists the files in the agent's currently-deployed release; read prints one file to stdout verbatim, so the output is pipeable. Both read at the release's commit, not at main HEAD — what you see is what the agent is actually running. Read-only: to edit, open a draft.

$ valet releases read my-agent SOUL.md > soul.md

Drafts

An agent may have at most one open draft. The full out-of-band editing loop:

drf=$(valet drafts create --agent my-agent)
cd "$(valet drafts checkout "$drf")"
$EDITOR skills/some-skill/SKILL.md
valet drafts validate "$drf"
valet drafts push "$drf"
valet drafts publish "$drf"
valet deploy --agent my-agent

List drafts

valet drafts [--agent <name>] [--org <org>]

Lists open drafts in the current org. Pass --agent to filter to a single agent. valet drafts info <draft_id> shows detail for one draft.

Open a draft

valet drafts create [-a <agent>] [--force]

Opens a fresh editing draft and prints the new draft id on stdout — only the id, so it composes with checkout. If a draft already exists this errors with the existing draft's id unless you pass --force, which discards it first.

Checkout a draft

cd "$(valet drafts checkout <draft_id>)"

Clones the draft branch to a local working directory under the system temp directory (one directory per draft id) and prints the absolute path on stdout. Running checkout again lays down a fresh tree at the current branch tip, discarding uncommitted local drift — push before re-running checkout if you have work to keep.

Validate a draft

valet drafts validate [draft-id] [--dir <path>]

Verifies the draft's valet.yaml parses against the manifest schema. Run this after editing files and before drafts push. With a draft-id, also checks that the current Git branch matches the draft's branch. Validating a copied working tree should omit the draft-id and pass --dir instead.

Push to a draft

valet drafts push <draft_id> [--dir <path>] [-m <message>]

Ships local file contents to the draft branch; the server commits the changed files. Nothing is published. When the working directory matches the draft tip exactly, the command exits 0 with No changes.

  • --dir — Directory to ship (default: the draft's checkout dir, else the current directory).
  • -m / --message — Commit message (default: "Update draft").

Publish a draft

valet drafts publish <draft_id>

Promotes the draft's branch to main and reports any catalog dependencies that need installing or attaching before the agent can deploy. When the manifest declares integrations or channels that aren't yet installed in the org, the status is needs_configuration; otherwise deployable. Publishing does not deploy — follow with valet deploy.

Discard a draft

valet drafts discard <draft_id>

Deletes the draft and its ephemeral branch without publishing. Cannot be undone.