cli

package
v0.7.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: Apache-2.0 Imports: 68 Imported by: 0

Documentation

Overview

Package cli wires axx's command-line interface.

Index

Constants

View Source
const (
	// CodePackHook: a hook a pack runs before or after a command failed,
	// with an error of its own rather than one of axx's.
	CodePackHook = "AXX-E0022"
	// CodeHookFailed: a hook of axx.yaml (hooks.commands) failed.
	CodeHookFailed = "AXX-E0023"
	// CodeHookCommand: a hook of axx.yaml names no command axx runs hooks
	// with, or runs nothing.
	CodeHookCommand = "AXX-E0106"
)
View Source
const CodeFmtWrite = "AXX-E0209"

CodeFmtWrite is a feature file `axx fmt` laid out but cannot write.

View Source
const CodePackArg = "AXX-E0011"

CodePackArg: an axx pack argument is invalid.

View Source
const CodePackCommand = "AXX-E0016"

CodePackCommand: a command a pack adds failed, with an error of its own rather than one of axx's.

View Source
const CodeRelaunch = "AXX-E0024"

CodeRelaunch: a pack could not run a command again in another process.

View Source
const EnvelopeSchemaVersion = 1

EnvelopeSchemaVersion is the version of the --json output envelope.

View Source
const Identity = `` /* 237-byte string literal not displayed */

Identity is the canonical one-liner used everywhere axx describes itself.

Variables

This section is empty.

Functions

func Main

func Main(args []string) int

Main runs the CLI with args and returns the process exit code.

func Run

func Run(ctx context.Context, app *App, args []string) int

Run executes the CLI with an explicit App (for tests and embedding).

Types

type App

type App struct {
	Stdout io.Writer
	Stderr io.Writer
	Env    func(string) string

	JSON    bool
	Compact bool
	Config  string
	Verbose int
	NoColor bool
	// contains filtered or unexported fields
}

App carries process-wide state shared by all commands.

func NewApp

func NewApp() *App

NewApp returns an App bound to the process's standard streams.

func (*App) Emit

func (a *App) Emit(data any, human func(w io.Writer) error) error

Emit writes a command result: the JSON envelope in --json mode, otherwise the human rendering produced by human (which may be nil).

func (*App) EmitResult

func (a *App) EmitResult(data any, ok bool, human func(w io.Writer) error) error

EmitResult is Emit for commands whose outcome can be unsuccessful without an error (e.g. validation problems): ok is reported in the envelope and must agree with the exit code.

type CheckReport

type CheckReport struct {
	BaseDir  string             `json:"baseDir"`
	Checks   int                `json:"checks"`
	Failures []fixtures.Failure `json:"failures"`
	// Unmaterialized are ignored outputs this checkout does not have yet,
	// which `axx fixtures generate` writes.
	Unmaterialized []string `json:"unmaterialized,omitempty"`
}

CheckReport is the JSON result of `axx fixtures check`.

type DocsServeResult added in v0.6.7

type DocsServeResult struct {
	URL     string `json:"url"`
	Version string `json:"version,omitempty"`
	Dir     string `json:"dir"`
}

DocsServeResult is the JSON result of `axx docs serve`, written as it starts serving.

type DoctorCheck

type DoctorCheck struct {
	Name   string `json:"name"`
	Status string `json:"status"` // ok | warn | fail
	Detail string `json:"detail,omitempty"`
	Hint   string `json:"hint,omitempty"`
}

DoctorCheck is one environment check.

type DoctorReport

type DoctorReport struct {
	Version version.Info  `json:"version"`
	Config  string        `json:"config,omitempty"`
	Packs   []PackSource  `json:"packs,omitempty"`
	Checks  []DoctorCheck `json:"checks"`
}

DoctorReport is the JSON result of `axx doctor`.

type Envelope

type Envelope struct {
	SchemaVersion int             `json:"schemaVersion"`
	Command       string          `json:"command"`
	OK            bool            `json:"ok"`
	Data          any             `json:"data,omitempty"`
	Errors        []EnvelopeError `json:"errors,omitempty"`
}

Envelope wraps every --json response so agents can parse any command uniformly (see docs/adr/0003-cli-contract.md).

type EnvelopeError

type EnvelopeError struct {
	Code     string           `json:"code,omitempty"`
	Message  string           `json:"message"`
	Location *axxerr.Location `json:"location,omitempty"`
	Hint     string           `json:"hint,omitempty"`
	Docs     string           `json:"docs,omitempty"`
}

EnvelopeError is the JSON form of an error.

type ExplainedArg

type ExplainedArg struct {
	Param   string `json:"param"`
	Present bool   `json:"present"`
	Raw     string `json:"raw,omitempty"`
}

ExplainedArg is one captured argument.

type ExplainedCode

type ExplainedCode struct {
	axxerr.Entry
	Docs string `json:"docs"`
}

ExplainedCode is the JSON result of `axx explain AXX-Exxxx`.

type ExplainedMatch

type ExplainedMatch struct {
	ID   string         `json:"id"`
	Pack string         `json:"pack"`
	Expr string         `json:"expr"`
	Args []ExplainedArg `json:"args"`
	Arg  string         `json:"argument"`
}

ExplainedMatch describes one matching definition.

type Explanation

type Explanation struct {
	Line        string             `json:"line"`
	Text        string             `json:"text"`
	Status      string             `json:"status"` // matched | undefined | ambiguous
	Match       *ExplainedMatch    `json:"match,omitempty"`
	Candidates  []ExplainedMatch   `json:"candidates,omitempty"`
	Suggestions []match.Suggestion `json:"suggestions,omitempty"`
}

Explanation is the JSON result of `axx explain`.

type FmtReport added in v0.6.5

type FmtReport struct {
	// Files is how many feature files it read.
	Files int `json:"files"`
	// Changed are the files it laid out, or, with --check, those it would.
	Changed []string `json:"changed"`
	Check   bool     `json:"check,omitempty"`
}

FmtReport is the JSON result of `axx fmt`.

type GenerateReport

type GenerateReport struct {
	BaseDir   string   `json:"baseDir"`
	DryRun    bool     `json:"dryRun,omitempty"`
	Written   []string `json:"written"`
	Unchanged []string `json:"unchanged"`
}

GenerateReport is the JSON result of `axx fixtures generate`.

type HookProblem added in v0.6.1

type HookProblem struct {
	Pack    string `json:"pack"`
	Command string `json:"command"`
	Phase   string `json:"phase"`
	Problem string `json:"problem"`
}

HookProblem is a pack's command hook that never runs, and why: `axx doctor` reports it.

type InitAgents added in v0.1.1

type InitAgents struct {
	// Detected are the agents the repository shows signs of using.
	Detected []string `json:"detected"`
	// Skills are where the skills were installed: .agents/skills, and
	// .claude/skills for Claude Code.
	Skills []InitFile `json:"skills"`
	// MCP are the agents' MCP configurations: written, already there, or
	// (Codex, whose servers live in the home directory) the command that adds axx.
	MCP []agents.Change `json:"mcp"`
}

InitAgents is what `axx init` set up for coding agents.

type InitFile

type InitFile struct {
	Path   string `json:"path"`
	Action string `json:"action"` // create | update | skip
	Reason string `json:"reason,omitempty"`
}

InitFile is one file `axx init` writes (or would write).

type InstallResult added in v0.5.0

type InstallResult struct {
	Version string `json:"version"`
	Path    string `json:"path"`
}

InstallResult is what `axx install` did.

type PackDetail added in v0.3.0

type PackDetail struct {
	Pack     string     `json:"pack"`
	Summary  string     `json:"summary"`
	Used     bool       `json:"used"`
	Requires []string   `json:"requires,omitempty"`
	Doc      string     `json:"doc,omitempty"`
	Settings []Setting  `json:"settings,omitempty"`
	Steps    []StepInfo `json:"steps"`
	// StepCount is the pack's number of steps (Steps may leave them out).
	StepCount int          `json:"stepCount"`
	Related   []PackSketch `json:"related,omitempty"`
}

PackDetail is `axx pack show`: a pack, what it reaches, its settings and its steps, as `axx steps` lists them (foldedSteps).

type PackInfo

type PackInfo struct {
	Pack  string `json:"pack"`
	Kind  string `json:"kind"`
	Steps int    `json:"steps"`
	Used  bool   `json:"used"`
	// Summary says what the pack reaches.
	Summary string `json:"summary,omitempty"`
}

PackInfo is one row of `axx pack list`.

type PackSketch added in v0.3.0

type PackSketch struct {
	Pack    string `json:"pack"`
	Summary string `json:"summary"`
}

PackSketch is a pack in one line.

type PackSource added in v0.1.1

type PackSource struct {
	Name    string `json:"name"`
	Module  string `json:"module"`
	Version string `json:"version,omitempty"`
	Dir     string `json:"dir,omitempty"`
}

PackSource is where a pack of this axx comes from: a module at a version, or a local directory.

func (PackSource) String added in v0.1.1

func (p PackSource) String() string

type PackSuggestion added in v0.3.0

type PackSuggestion struct {
	Pack    string   `json:"pack"`
	Reasons []string `json:"reasons"`
}

PackSuggestion is a pack of axx's that `axx init` suggests for a repository, and what in the repository suggests it.

type ParamInfo

type ParamInfo struct {
	Name string `json:"name"`
	Doc  string `json:"doc,omitempty"`
}

ParamInfo describes a parameter used by a step.

type Problem

type Problem struct {
	Kind        string             `json:"kind"` // undefined | ambiguous | argument | value
	Location    string             `json:"location"`
	Text        string             `json:"text"`
	Message     string             `json:"message,omitempty"`
	Suggestions []match.Suggestion `json:"suggestions,omitempty"`
	Candidates  []string           `json:"candidates,omitempty"`
}

Problem is one validation finding.

type Setting added in v0.3.0

type Setting struct {
	Key string `json:"key"`
	Doc string `json:"doc,omitempty"`
}

Setting is a key of a pack's section in axx.yaml (packs.<name>).

type StepInfo

type StepInfo struct {
	ID       string   `json:"id"`
	Pack     string   `json:"pack"`
	Expr     string   `json:"expr"`
	Variants []string `json:"variants"`
	Keyword  string   `json:"keyword,omitempty"`
	Arg      string   `json:"arg"`
	// Columns name the columns of the step's data table, when it has one;
	// Rows are the rows it knows (a service's properties), and TableNote
	// says what its rows hold.
	Columns    []string        `json:"columns,omitempty"`
	Rows       []core.TableRow `json:"rows,omitempty"`
	TableNote  string          `json:"tableNote,omitempty"`
	Doc        string          `json:"doc,omitempty"`
	Examples   []string        `json:"examples,omitempty"`
	Params     []ParamInfo     `json:"params,omitempty"`
	Since      string          `json:"since,omitempty"`
	Deprecated string          `json:"deprecated,omitempty"`
	// Twin is the id of the step's form for a named service (`… on
	// {service}`), where a list folds that form into its step.
	Twin string `json:"twin,omitempty"`
}

StepInfo is the JSON description of a step definition.

type UpgradeChange added in v0.5.0

type UpgradeChange struct {
	Version  string               `json:"version"`
	Date     string               `json:"date,omitempty"`
	Sections []selfupdate.Section `json:"sections,omitempty"`
}

UpgradeChange is what one release changed.

type UpgradeCheck added in v0.5.0

type UpgradeCheck struct {
	Command string `json:"command"`
	OK      bool   `json:"ok"`
	Output  string `json:"output,omitempty"`
}

UpgradeCheck is one check of a project on the version it moved to.

type UpgradeResult added in v0.5.0

type UpgradeResult struct {
	From     string `json:"from"`
	To       string `json:"to"`
	Path     string `json:"path"`
	Method   string `json:"method"`
	UpToDate bool   `json:"upToDate,omitempty"`
	// Available: --check, which changes nothing, found a newer release.
	Available bool            `json:"available,omitempty"`
	Upgraded  bool            `json:"upgraded,omitempty"`
	Changes   []UpgradeChange `json:"changes,omitempty"`
	// Skills are the skills it updated, by scope; SkillsProblem says why it could not.
	Skills        []string `json:"skills,omitempty"`
	SkillsProblem string   `json:"skillsProblem,omitempty"`
	// Project: From and To are the versions this project's axx.yaml names, and Path
	// is that file.
	Project bool `json:"project,omitempty"`
	// Checks are `axx validate` and `axx lint` on the version the project moved to.
	Checks []UpgradeCheck `json:"checks,omitempty"`
	// Installed is what became of the installed axx, which a project's move takes
	// along when it is older; InstalledProblem says why it could not.
	Installed        *UpgradeResult `json:"installed,omitempty"`
	InstalledProblem string         `json:"installedProblem,omitempty"`
}

UpgradeResult is what `axx upgrade` did.

type ValidationReport

type ValidationReport struct {
	Files     int       `json:"files"`
	Scenarios int       `json:"scenarios"`
	Steps     int       `json:"steps"`
	Problems  []Problem `json:"problems"`
	// Warnings come from the builtin feature checks of `axx lint`; they do
	// not change the exit code.
	Warnings []Problem `json:"warnings,omitempty"`
	// Hints name scenarios whose checks prove little, as `axx lint` does;
	// they are for the author to judge and do not change the exit code.
	Hints []string `json:"hints,omitempty"`
}

ValidationReport is the JSON result of `axx validate`.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL