cli

Documentation

Overview

Package cli is the wiring layer. It parses argv into a Command, dispatches to the selected Provider, and hands the result to the renderer. It owns no formatting and no history-reading logic of its own — it only sequences the other layers. The pipeline reads top to bottom: parse, locate, read, render.

Index

• Constants
• func Run(ctx context.Context, args []string, roots session.Roots, ...) error
• type Command
  • func Parse(args []string) (Command, error)

Constants

const DefaultLimit = session.DefaultListLimit

DefaultLimit is the number of rows a listing returns when -n is not given.

Functions

func Run

func Run(ctx context.Context, args []string, roots session.Roots, current map[string]string, skillDirs map[string]string, skillMD []byte, version, cwd string, stdin io.Reader, stdout, stderr io.Writer) error

Run executes one invocation. current maps a provider name to the id of the session we are running inside, when that agent injects one (see session.ResolveCurrent); it lets the default selection target the live session exactly rather than guessing by recency. skillDirs maps a provider name to its global Agent Skills directory (see session.ResolveSkillDirs) and skillMD is the SKILL.md content to install there; install-skill writes them, every other action reads skillDirs to warn when an installed copy drifts from this build. version is the stamped build version that --version reports.

Types

type Command

type Command struct {
	Action       string // optional action subcommand; empty means render history
	Into         string // --into <agent>: with fork, seed that agent with the transcript
	Model        string // --model <name>: with fork, launch the agent with this model
	From         string // --from <file|-|http(s) url>: with fork --into, seed from this artifact instead of a provider store
	Dir          string // --dir <path>: select sessions from this directory instead of the cwd
	Target       session.Target
	Format       session.Format
	MetaOnly     bool // -i: render metadata/frontmatter only
	Full         bool // --full: render oversized entries whole instead of clamped
	LastN        int  // --last N: keep only the last N exchanges/turns (0 = all)
	SinceCompact bool // --since-compact: keep only the final compaction segment
	List         bool // --list: print the ranked listing and exit
	Limit        int  // -n N: cap listing rows (defaults to DefaultLimit)
	Help         bool // --help, -h: print usage and exit
	Version      bool // --version: print the binary version and exit
}

Command is the fully parsed, normalized form of a single catchup invocation: what to select (Target) and how to present it. It is the parser's only output and the cli's only input, so that argument syntax lives in exactly one place and the rest of the program works with structured data.

func Parse

func Parse(args []string) (Command, error)

Parse turns raw argv (excluding the program name) into a Command. It accepts the fixed grammar:

catchup [agent[/<rank>]] [flags]

The agent may be omitted; the cli then detects the agent with the newest session in the working directory (Target.Provider stays empty here).

Flags may appear before or after the target, which is why this is a small hand-rolled parser rather than the stdlib flag package (which stops at the first non-flag argument). Parse is purely syntactic plus a normalization pass; it does not check whether the provider actually exists — that belongs to the cli dispatch (selectProvider).