Documentation
¶
Overview ¶
Package cli provides the Cobra-based command-line interface for AWF.
The CLI layer is the primary user-facing entry point, translating command-line invocations into application service calls. All commands follow the hexagonal architecture pattern: CLI → Application Services → Domain → Infrastructure. The package handles user input collection, output formatting, signal handling, and exit code mapping according to the AWF error taxonomy.
Architecture Role ¶
In the hexagonal architecture:
- CLI commands receive user input from cobra.Command flags and arguments
- Commands delegate business logic to application services (WorkflowService, ExecutionService)
- Commands handle cross-cutting concerns: signal handling, exit codes, output formatting
- Commands inject infrastructure adapters (repositories, loggers, executors) into services
The CLI layer is an adapter in the "interfaces" layer, depending on both application services (orchestration) and infrastructure adapters (implementation details). No domain logic resides here—only input parsing, output rendering, and coordination.
Command Structure ¶
## Root Command (root.go)
Application container and version command:
- App: Dependency injection container with Config and Formatter
- NewApp: Creates application with loaded configuration
- NewRootCommand: Builds cobra command tree with global flags
- --version: Displays AWF version, commit, and build date
Global flags:
- --no-color: Disable colorized output
- --json: JSON-formatted output
- --no-hints: Suppress helpful tips
## Core Commands
### run (run.go)
Execute workflow with state machine traversal:
- Flags: --input, --resume, --agent-input, --mock, --dry-run, --interactive, --no-save
- Input resolution: CLI flags → project config → interactive prompts
- Dry run mode: validates without execution, renders execution plan
- Interactive mode: step-by-step execution with user confirmation
- Resume support: continues from saved checkpoint state
- Error categorization: maps domain/infra errors to exit codes (1-4)
### list (list.go)
Enumerate available workflows and prompts:
- list: Display all workflows from configured paths
- list prompts: Show available interactive prompts with descriptions
- Output format: table (default) or JSON
### validate (validate.go)
Static workflow validation:
- Parse workflow YAML
- Validate structure, state references, transitions
- Check for cycles, unreachable states
- Exit 0 on success, 2 on validation errors
### status (status.go)
Check running workflow status:
- Query execution state from StateStore
- Display current step, progress, outputs
- Show execution timeline and duration
### resume (resume.go)
Continue interrupted workflow:
- Load checkpoint state from StateStore
- Resume execution from last completed step
- Preserve input values and outputs
### history (history.go)
Query workflow execution history:
- List past executions with filtering (workflow name, status, date range)
- Show execution statistics (duration, success rate)
- Prune old history records
## Supporting Commands
### init (init.go)
Initialize AWF in current directory:
- Create .awf/ directory structure
- Generate default awf.yaml configuration
- Create workflows/ directory with example
### config (config.go, config_cmd.go)
Configuration management:
- config show: Display current configuration
- config set <key> <value>: Update configuration value
- config paths: Show search paths for workflows/templates/plugins
### plugin (plugin_cmd.go, plugins.go)
Plugin lifecycle management:
- plugin list: Show available plugins
- plugin enable <name>: Activate plugin
- plugin disable <name>: Deactivate plugin
- plugin status <name>: Check plugin state
### diagram (diagram.go)
Generate workflow visualization:
- Render workflow state machine as Mermaid diagram
- Output to stdout or file
### migration (migration.go)
Version migration utilities:
- Migrate workflow syntax to latest version
- Update deprecated fields
Signal Handling (signal_handler.go) ¶
Graceful shutdown on SIGINT/SIGTERM:
- setupSignalHandler: Starts goroutine listening for OS signals
- Context cancellation: Propagates cancellation through execution stack
- Process group cleanup: Terminates child processes on signal
- Cleanup callback: Executes user-provided cleanup function before exit
- Goroutine leak prevention: Returns cleanup function that MUST be deferred
Exit Codes (exitcodes.go) ¶
AWF error taxonomy mapping:
- ExitSuccess (0): Successful execution
- ExitUser (1): User error (bad input, missing file, invalid flags)
- ExitWorkflow (2): Workflow error (invalid state reference, cycle detection, schema violation)
- ExitExecution (3): Execution error (command failed, timeout, agent error)
- ExitSystem (4): System error (IO failure, permissions, resource exhaustion)
Error Handling (error.go) ¶
Error categorization and formatting:
- exitError: Wraps domain/infra errors with exit code
- categorizeError: Maps error types to exit codes via taxonomy
- writeErrorAndExit: Formats error, writes to stderr, exits with correct code
- formatLog: Colorized log output with level-based styling
Design Principles ¶
- Thin adapter layer: All business logic in application/domain layers
- Fail fast: Validate inputs before service calls
- User-friendly errors: Context-rich messages with actionable guidance
- Testability: Commands accept io.Writer for output, injectable services
- Signal safety: Always defer signal handler cleanup to prevent leaks
- Exit code discipline: Consistent taxonomy mapping for automation/scripting
Index ¶
- Constants
- Variables
- func AttachMirrorSubscriber(rec ports.Recorder, mirrorPath string) func()
- func BuildPluginPaths() []repository.SourcedPath
- func BuildPromptPaths() []repository.SourcedPath
- func BuildWorkflowPaths() []repository.SourcedPath
- func CheckMigration(w io.Writer)
- func NewRecorderFactory() ports.RecorderFactory
- func NewRootCommand() *cobra.Command
- func NewRootCommandAutoFacade() (cmd *cobra.Command, cleanup func())
- func NewServeCommand() *cobra.Command
- func NewWorkflowRepository() *repository.CompositeRepository
- func ParseMockFlags(flags []string) (map[string]string, error)
- func RenderFacadeEventsToText(events []ports.Event) []byte
- func RenderFacadeEventsToTextWithOptions(events []ports.Event, opts facadeRenderOptions) []byte
- func RenderWorkflowHelp(cmd *cobra.Command, wf *workflow.Workflow, out io.Writer, noColor bool) error
- func WireTranscript(runID, storageRoot string) (ports.Recorder, func() error, error)
- type App
- type Config
- type ConfigShowOutput
- type Deps
- type HistoryInfo
- type HistoryStatsInfo
- type OutputMode
- type PluginSystemResult
Constants ¶
const ( ExitSuccess = 0 // Success ExitUser = 1 // User error (bad input, missing file) ExitWorkflow = 2 // Workflow error (invalid state reference, cycle) ExitExecution = 3 // Execution error (command failed, timeout) ExitSystem = 4 // System error (IO, permissions) )
Exit codes following the error taxonomy
Variables ¶
var ( Version = "dev" Commit = "unknown" BuildDate = "unknown" )
Version information (set at build time via ldflags)
Functions ¶
func AttachMirrorSubscriber ¶ added in v0.11.2
AttachMirrorSubscriber attaches a debug mirror subscriber to the recorder. When mirrorPath is non-empty, recorder events are written to mirrorPath; when empty, returns a no-op cancel. The actual subscription lives in the transcript infrastructure (transcript.MirrorToFile) so the interface layer holds no direct recorder.Subscribe() call, preserving the SC-001 sole-subscriber invariant.
func BuildPluginPaths ¶
func BuildPluginPaths() []repository.SourcedPath
BuildPluginPaths returns plugin paths in priority order: 1. AWF_PLUGINS_PATH env var 2. ./.awf/plugins/ (local project) 3. $XDG_DATA_HOME/awf/plugins/ (global)
func BuildPromptPaths ¶
func BuildPromptPaths() []repository.SourcedPath
BuildPromptPaths returns the prompt paths in priority order: 1. ./.awf/prompts/ (local project) 2. $XDG_CONFIG_HOME/awf/prompts/ (global)
func BuildWorkflowPaths ¶
func BuildWorkflowPaths() []repository.SourcedPath
BuildWorkflowPaths returns the workflow paths in priority order: 1. AWF_WORKFLOWS_PATH env var 2. ./.awf/workflows/ (local project) 3. $XDG_CONFIG_HOME/awf/workflows/ (global)
func CheckMigration ¶
CheckMigration shows a one-time migration notice if ~/.awf exists
func NewRecorderFactory ¶ added in v0.11.2
func NewRecorderFactory() ports.RecorderFactory
NewRecorderFactory returns a ports.RecorderFactory backed by the transcript infrastructure Recorder. It is used by ExecutionService to create one child recorder per sub-run for F106 sub-workflow transcript linkage. The parent directory of the path passed to the factory must already exist.
func NewRootCommand ¶
func NewRootCommandAutoFacade ¶ added in v0.11.2
NewRootCommandAutoFacade builds the root command with a CLI-wide WorkflowFacade wired into cfg.Facade lazily (in PersistentPreRun, after flag parsing so --storage is honored). It returns the command and a cleanup that releases facade resources (closes the history store); main must call it after Execute returns.
func NewServeCommand ¶ added in v0.11.2
NewServeCommand returns the cobra.Command for `awf serve`.
func NewWorkflowRepository ¶
func NewWorkflowRepository() *repository.CompositeRepository
NewWorkflowRepository creates a CompositeRepository with standard paths
func ParseMockFlags ¶
ParseMockFlags parses --mock flags into a map. Format: states.step_name.Output=value
func RenderFacadeEventsToText ¶ added in v0.11.2
RenderFacadeEventsToText converts facade events to CLI text output in the default (non-quiet) mode. This is the renderer the facade conformance golden exercises; the live run driver uses RenderFacadeEventsToTextWithOptions to honor --quiet.
func RenderFacadeEventsToTextWithOptions ¶ added in v0.11.2
RenderFacadeEventsToTextWithOptions converts facade events to CLI text output, honoring the supplied options (e.g. --quiet). It restores the legacy phrasing so downstream tooling and users that grep "Workflow ID:" / "completed successfully" keep working:
- EventRunStarted prints both a human "Workflow started:" line and the legacy "Workflow ID: <run-id>" line (suppressed in quiet mode via Info).
- EventStepCompleted prints the legacy "<step>: completed successfully" feedback line for a silent step (no stdout/stderr), suppressed in quiet mode; a step that already printed output gets a plain completion marker instead (its output is the feedback).
func RenderWorkflowHelp ¶
func RenderWorkflowHelp(cmd *cobra.Command, wf *workflow.Workflow, out io.Writer, noColor bool) error
RenderWorkflowHelp renders workflow-specific help output including workflow description and input parameters table. This is called when a user runs `awf run <workflow> --help` to display dynamic help for the specified workflow.
The output follows Cobra help conventions while adding workflow-specific content: - Workflow description (if present) - Input parameters table with NAME, TYPE, REQUIRED, DEFAULT, DESCRIPTION columns
func WireTranscript ¶ added in v0.11.2
WireTranscript builds a transcript Recorder at storage/transcripts/<runID>.jsonl and returns the recorder along with a cleanup closure that calls Close(). The storageRoot is the parent directory for transcripts (typically cfg.StoragePath). Returns the recorder, a cleanup function, and any error.
Types ¶
type Config ¶
type Config struct {
Verbose bool
Quiet bool
NoColor bool
NoHints bool
OutputMode OutputMode
OutputFormat ui.OutputFormat
LogLevel string
ConfigPath string
StoragePath string
PluginsDir string // Override plugin discovery directory (empty = use BuildPluginPaths)
OtelExporter string
OtelServiceName string
Facade ports.WorkflowFacade // nil until wired via NewRootCommandWithFacade or main.go
}
Config holds CLI configuration.
type ConfigShowOutput ¶
type ConfigShowOutput struct {
Path string `json:"path"`
Exists bool `json:"exists"`
Inputs map[string]any `json:"inputs,omitempty"`
}
ConfigShowOutput represents the structured output for 'config show' command. Used for JSON format output.
type Deps ¶ added in v0.11.2
type Deps struct {
PluginManager ports.PluginManager
OperationProviders map[string]ports.OperationProvider
}
Deps holds injectable dependencies for the mcp-serve subcommand.
When Deps is populated (test or future in-process callers), runMCPServe uses OperationProviders directly for plugin_tools resolution. When Deps is empty (the subprocess case — ProxyService.StartForStdio spawns `awf mcp-serve` with no in-process state), runMCPServe self-bootstraps by calling initPluginSystem, which loads external plugins from the standard discovery paths. Either code path converges on the same registerTools call.
type HistoryInfo ¶
type HistoryInfo struct {
ID string `json:"id"`
WorkflowID string `json:"workflow_id"`
WorkflowName string `json:"workflow_name"`
Status string `json:"status"`
ExitCode int `json:"exit_code,omitempty"`
StartedAt string `json:"started_at"`
CompletedAt string `json:"completed_at"`
DurationMs int64 `json:"duration_ms"`
ErrorMessage string `json:"error_message,omitempty"`
}
type HistoryStatsInfo ¶
type OutputMode ¶
type OutputMode int
OutputMode defines how command output is displayed.
const ( OutputSilent OutputMode = iota // default: no streaming OutputStreaming // real-time prefixed output OutputBuffered // show after completion )
func ParseOutputMode ¶
func ParseOutputMode(s string) (OutputMode, error)
ParseOutputMode parses a string to OutputMode.
func (OutputMode) String ¶
func (m OutputMode) String() string
type PluginSystemResult ¶
type PluginSystemResult struct {
Service *application.PluginService
Manager ports.OperationProvider
RPCManager *infrastructurePlugin.RPCPluginManager // for validator/step-type providers (C069)
StateStore *infrastructurePlugin.JSONPluginStateStore
EventPublisher ports.EventPublisher
Cleanup func()
}
PluginSystemResult contains the initialized plugin system components.
Source Files
¶
- acp_serve.go
- acp_wiring.go
- config.go
- config_cmd.go
- diagram.go
- doc.go
- error.go
- exitcodes.go
- history.go
- init.go
- list.go
- mcp_serve.go
- migration.go
- pack_resolver.go
- plugin_cmd.go
- plugin_init_cmd.go
- plugin_init_generate.go
- plugin_init_options.go
- plugin_init_template.go
- plugin_init_templates.go
- plugins.go
- release_target.go
- resume.go
- resume_list.go
- root.go
- run.go
- run_facade_projector.go
- run_help.go
- serve.go
- signal_handler.go
- status.go
- upgrade.go
- validate.go
- wiring_transcript.go
- workflow_cmd.go