Documentation
¶
Overview ¶
Package cli defines agentctl commands, global flags (design doc section 11.1), and exit-code mapping (section 11.2). Output formatting lives in render.
The init command scaffolds a minimal project from embedded templates (section 10.2).
The new command (issue #113) scaffolds individual Tool, Policy, Workflow, or Agent resources under conventional paths and appends them to project.yaml imports with atomic rollback-safe writes.
The validate command (section 10.2) loads the project, applies defaults and optional environment overlays, then runs spec.ValidateProjectGraph.
The fmt command (section 10.2) rewrites YAML files in the project import closure via project.ListProjectYAMLFiles and project.NormalizeYAML, with optional --check for CI.
The inspect command (section 10.2) uses the same preparation pipeline and prints one effective normalized resource envelope (Kind/name) as JSON, YAML, or indented JSON for table output. With --web it serves a read-only local inspector via inspect over SQLite state (issue #109).
The state command (section 10.2, §14.1) lists or shows rows from the SQLite deployment store (applied_resources, applied_projects) read-only via state.DeploymentStore.
The test command (section 10.2, §17.4) runs YAML workflow fixtures from <project>/tests/ via testkit.
The plan command compares that prepared graph to the SQLite deployment store (default .agentic/state.db, or project.spec.state.dsn / --state) and prints a diff plus risk delta via plan.ComputePlan and plan.FormatPlan.
The diff command uses the same comparison but prints a detailed per-resource view (field-level updates, full JSON for creates/deletes) and supports an optional Kind/name argument (§10.2).
The apply command runs the same preparation and planning, then prompts on a TTY (unless --auto-approve or AGENTCTL_AUTO_APPROVE) and persists via apply.Applier.ApplyPlan.
The run command executes a workflow by name (workflow/<name>), validates input, writes trace rows to the same SQLite file as plan/apply, and maps policy denials to exit code 5.
The logs command reads runs and trace_events from that SQLite file (ordered by seq per run) and supports listing recent runs, filtering by --run, or by --workflow.
The audit command (issue #116) verifies tamper-evident hash chains over trace_events via audit.VerifyRunChain; see docs/AUDIT_CHAIN.md.
Index ¶
- Constants
- Variables
- func BindPersistentFlags(cmd *cobra.Command)
- func Execute() error
- func ExitCodeOf(err error) int
- func Main() int
- func NewExitError(code int, err error) error
- func NewExitErrorf(code int, format string, a ...any) error
- func NewRootCmd() *cobra.Command
- func ParseResourceRef(s string) (spec.ResourceID, error)
- func ResetGlobalsForTest()
- func ValidateGlobals() error
- type ExitError
- type Global
Constants ¶
const ( ExitSuccess = 0 ExitGenericFailure = 1 ExitValidationError = 2 ExitPlanApplyConflict = 3 ExitExecutionError = 4 ExitPolicyDenied = 5 )
Exit codes (design doc section 11.2).
const EnvActorID = "AGENTCTL_ACTOR_ID"
EnvActorID overrides --actor-id when the flag is omitted.
const EnvAutoApprove = "AGENTCTL_AUTO_APPROVE"
EnvAutoApprove is read when true-like to skip the apply confirmation prompt (non-TTY / CI).
const EnvHitlActor = "AGENTCTL_HITL_ACTOR"
EnvHitlActor overrides the actor recorded on approval trace events.
const EnvRequireAttribution = "AGENTCTL_REQUIRE_ATTRIBUTION"
EnvRequireAttribution, when set to a truthy value, requires explicit tenant/thread/actor ids on run.
const EnvTenantID = "AGENTCTL_TENANT_ID"
EnvTenantID overrides --tenant-id when the flag is omitted.
const EnvThreadID = "AGENTCTL_THREAD_ID"
EnvThreadID overrides --thread-id when the flag is omitted.
Variables ¶
var Version = "0.0.0-dev"
Version is set at link time; default for dev builds.
Functions ¶
func BindPersistentFlags ¶
BindPersistentFlags registers -e/--env, -o/--output, --project, --state, --no-color on cmd.
func ExitCodeOf ¶
ExitCodeOf maps errors to process exit codes. Unknown errors use ExitGenericFailure.
func Main ¶
func Main() int
Main is an optional entrypoint that maps errors to exit codes and writes diagnostics to stderr.
func NewExitError ¶
NewExitError wraps err with a specific exit code.
func NewExitErrorf ¶
NewExitErrorf is like fmt.Errorf with an exit code.
func NewRootCmd ¶
NewRootCmd builds the agentctl command tree (exposed for tests).
func ParseResourceRef ¶ added in v0.1.4
func ParseResourceRef(s string) (spec.ResourceID, error)
ParseResourceRef parses a CLI resource argument as Kind/name (e.g. Policy/default, workflow/hello). Kind is matched case-insensitively and normalized to spec kind constants.
func ResetGlobalsForTest ¶
func ResetGlobalsForTest()
ResetGlobalsForTest resets global flags (for tests only).
func ValidateGlobals ¶
func ValidateGlobals() error
ValidateGlobals checks flag values after parsing.
Types ¶
type ExitError ¶
ExitError carries a non-zero exit status for ExitCodeOf.
Source Files