CLI reference

Every vago command with its arguments, flags and an example, as its --help prints them.

Each command below is what vago <command> --help prints. vago --help lists them all:

usage: vago <command> [arguments]

vago takes a Goal's Tickets through the Workflow the Goal names, with a coding
agent doing each agent Step.

commands:
  init           Copy the starter Workflows into .vago/ of this repo
  update         Bring .vago/ and the vago- skills to this vago's starter
  run            Take a Goal's Tickets through its Workflow
  goal new       Create a Goal with no Tickets
  goal report    Print a Markdown report of a Goal's Tickets and Runs
  plan new       Start planning a Goal
  plan rename    Rename a planning item
  plan session   Run a planning item's agent in its Harness's own session
  plan workflow  Choose the Workflow a planning item's Goal goes through
  plan accept    Accept a planning item's proposal as a ready Goal
  plan discard   Remove a planning item and everything it holds
  ticket add     Add a ready Ticket to a Goal
  ticket reset   Make a stuck Ticket start over from its first Step

Run `vago <command> --help` for a command's arguments, flags and an example.

vago init

Copy the starter Workflows into .vago/ of this repo.

usage: vago init

Copies the starter Workflows, prompts and scripts into .vago/, and the vago-
skills into .claude/skills/ for Claude Code and .agents/skills/ for Codex. It
first asks whether you will commit the Workflow: yes leaves them to git,
anything else adds .vago/ and each skill to .git/info/exclude. Goals stay out
of git either way. It refuses, changing nothing, when a file it would write
already exists or this is not the root of a git repo. To bring a set-up
Project to a newer starter, run vago update.

example:
  vago init

vago update

Bring .vago/ and the vago- skills to this vago’s starter.

usage: vago update

Overwrites each starter file in .vago/, .claude/skills/ and .agents/skills/
that differs from the starter this vago ships, writes the ones that are
missing, and prints the path of each file it changed. Files you added, such as
your own Workflow, prompt or skill, and the Goals in .vago-goals/ stay as they
are. It keeps the commit answer you gave vago init, and asks again only when
.git/info/exclude doesn't show it. It refuses when there is no .vago/ yet:
run vago init.

example:
  vago update

vago run

Take a Goal’s Tickets through its Workflow.

usage: vago run <goal>

Runs the Goal's ready and stuck Tickets through the Steps of the Workflow the
Goal names, one Ticket at a time, until no Ticket is left to run or one goes
stuck. A ready Ticket starts at the first Step, and a stuck, interrupted or
lost one continues at the Step it stopped on. It
prints a line per Step and a summary at the end. Exits 0 only when every
Ticket is done. The Steps run in the Goal's own worktree, outside the repo on
branch vago/<goal>, whose path it prints. It refuses a Goal another vago run
is running.

arguments:
  <goal>  The Goal to run.

example:
  vago run search

vago goal new

Create a Goal with no Tickets.

usage: vago goal new <goal> --workflow <name> [--body-file <path>]

Creates the Goal with no Tickets and prints the path of its goal.md. It refuses,
creating nothing, when the Goal exists or vago run would refuse the Workflow.

arguments:
  <goal>              The new Goal's name, used for its folder.

flags:
  --workflow <name>   The Workflow the Goal's Tickets go through, from .vago/workflows/<name>.toml.
  --body-file <path>  Takes the body from this file, or from stdin when <path> is -. Without it, the body is a title to fill in.

example:
  vago goal new search --workflow small --body-file goal.md

vago goal report

Print a Markdown report of a Goal’s Tickets and Runs.

usage: vago goal report <goal>

Prints the Goal's body, then a table of its Tickets with the Runs each took,
how long they took and what they cost, ready to paste into a PR description.

arguments:
  <goal>  The Goal to report on.

example:
  vago goal report search

vago plan new

Start planning a Goal.

usage: vago plan new <name> [--harness <name>]

Makes a planning item, a Goal still being planned, and prints its folder. It
shows in the TUI's Goals list as planning. Its agent runs on the Harness
chosen here for every session, whatever Harness the accepted Goal's Workflow
uses. It makes no Goal and no Ticket, so vago run doesn't find it. It refuses
a name a Goal or planning item has.

arguments:
  <name>            The planning item's name, which the Goal keeps unless it is renamed.

flags:
  --harness <name>  The Harness the planning agent runs on, claude-code or codex. Without it, claude-code when its claude is on PATH, else codex when its codex is.

example:
  vago plan new search --harness codex

vago plan rename

Rename a planning item.

usage: vago plan rename <name> <new-name>

Gives a planning item a new name, keeping everything it holds. It refuses a
Goal, a name a Goal or planning item has, and an item while its planning
session is open.

arguments:
  <name>      The planning item's name.
  <new-name>  The name it takes.

example:
  vago plan rename search ranked-search

vago plan session

Run a planning item’s agent in its Harness’s own session.

usage: vago plan session <name>

Runs the planning item's agent in its Harness's own session on this terminal,
resuming the item's session when it has one, until the session ends. The agent
can read the Project but not write under it. The TUI runs it beside the
Preview. For a Goal accepted from a planning item, it resumes the session to
read, and nothing the agent writes changes the Goal.

arguments:
  <name>  The planning item's name.

example:
  vago plan session search

vago plan workflow

Choose the Workflow a planning item’s Goal goes through.

usage: vago plan workflow <name> <workflow>

Records the Workflow the planning item's Goal will go through once accepted.
The choice wins over the agent's recommendation and stays through every
revision of the proposal. It refuses a Workflow that isn't in
.vago/workflows/, naming the ones that are.

arguments:
  <name>      The planning item's name.
  <workflow>  The name of a Workflow in .vago/workflows/, without .toml.

example:
  vago plan workflow search try-hard

vago plan accept

Accept a planning item’s proposal as a ready Goal.

usage: vago plan accept <name>

Turns the planning item into a ready Goal with its proposed Tickets, all at
once, and prints the path of its goal.md. It refuses, creating nothing, when
the proposal isn't ready to accept, vago run would refuse its Workflow, its
planning session is open, or the item was already accepted. It starts
nothing: vago run does.

arguments:
  <name>  The planning item's name.

example:
  vago plan accept search

vago plan discard

Remove a planning item and everything it holds.

usage: vago plan discard <name>

Removes a planning item and everything saved with it. Its open planning
session is stopped first. It refuses a Goal, which it never removes.

arguments:
  <name>  The planning item's name.

example:
  vago plan discard search

vago ticket add

Add a ready Ticket to a Goal.

usage: vago ticket add <goal> <slug> [--blocked-by <NN>]... [--workflow <name>] [--body-file <path>]

Adds a Ticket to the Goal, numbered one past its highest Ticket, with status
ready, and prints the path of the Ticket file. The Ticket goes through the
Goal's Workflow unless --workflow names another. It refuses, writing nothing,
when vago run would refuse that Workflow.

arguments:
  <goal>              The Goal the Ticket belongs to.
  <slug>              The Ticket's name, used in its file name after the number.

flags:
  --blocked-by <NN>   The number of a Ticket that must be done before this one runs. Repeat it for each blocker.
  --workflow <name>   The Workflow this Ticket goes through in place of the Goal's, from .vago/workflows/<name>.toml.
  --body-file <path>  Takes the body from this file, or from stdin when <path> is -. Without it, the body is a title to fill in.

example:
  vago ticket add search ranking --blocked-by 1 --body-file ticket.md

vago ticket reset

Make a stuck Ticket start over from its first Step.

usage: vago ticket reset <goal> <NN>

Sets a stuck Ticket so the next vago run starts it over from its first Step,
instead of picking it up at the Step it stopped on. Its Runs stay in the
Ticket file. It refuses a Ticket that isn't stuck.

arguments:
  <goal>  The Goal the Ticket belongs to.
  <NN>    The Ticket's number, the digits its file name starts with.

example:
  vago ticket reset search 2

This page as Markdown