afcli

Documentation

Overview

Package afcli provides Cobra command factories for the AgentFactory CLI. Downstream projects can import this package and call RegisterCommands to add the shared af subcommands to their own root command.

Package afcli exports.go — public factory functions for the four daemon-targeted command trees (provider, kit, workarea, routing).

Most afcli factories stay unexported and reach root via RegisterCommands. The four daemon-targeted families need public factories so downstream binaries can graft them under their own parent commands (e.g. `rensei host provider`, `rensei host kit`, `rensei host workarea`) without re-implementing the surface.

The factories return a fresh *cobra.Command tree on each call so callers can attach the same logical surface under multiple parents (e.g. both at top-level via RegisterCommands and nested under `host`) without sharing mutable command state.

All four trees target the local daemon's HTTP control API per ADR-2026-05-07-daemon-http-control-api.md. They never hit the SaaS platform and never attach an Authorization header (D2 — localhost-only). The ds argument is accepted for signature consistency with the rest of afcli but is unused — daemon-targeted commands resolve their client via RENSEI_DAEMON_URL or the 127.0.0.1:7734 default.

Package afcli kit.go — `af kit …` Cobra commands. The commands target the local daemon's HTTP control API at /api/daemon/kits* and /api/daemon/kit-sources* per ADR-2026-05-07-daemon-http-control-api.md § D1; they NEVER hit the SaaS platform and never attach an Authorization header (D2 — localhost-only).

Package afcli provider.go — `af provider …` Cobra commands. The commands target the local daemon's HTTP control API at /api/daemon/providers* per ADR-2026-05-07-daemon-http-control-api.md §D1; they NEVER hit the SaaS platform and never attach an Authorization header (D2 — localhost-only).

Package afcli routing.go — `af routing …` Cobra commands. The commands target the local daemon's HTTP control API at /api/daemon/routing/* per ADR-2026-05-07-daemon-http-control-api.md §D1; they NEVER hit the SaaS platform and never attach an Authorization header (D2 — localhost-only).

Package afcli workarea.go — `af workarea …` Cobra commands. The commands target the local daemon's HTTP control API at /api/daemon/workareas* per ADR-2026-05-07-daemon-http-control-api.md §D1 + §D4a; they NEVER hit the SaaS platform and never attach an Authorization header (D2 — localhost-only).

Index

• Constants
• func NewKitCmd(ds func() afclient.DataSource) *cobra.Command
• func NewProviderCmd(ds func() afclient.DataSource) *cobra.Command
• func NewRoutingCmd(ds func() afclient.DataSource) *cobra.Command
• func NewWorkareaCmd(ds func() afclient.DataSource) *cobra.Command
• func RegisterCommands(root *cobra.Command, cfg Config)
• type AnalysisResult
• type BranchCleanResult
• type BranchError
• type CleanupResult
• type Config
• type DraftedIssue
• type PatternMatch
• type WorktreeError
• type WorktreeResult

Constants

const DefaultAgentRunDaemonURL = "http://127.0.0.1:7734"

DefaultAgentRunDaemonURL is the local control HTTP address the daemon binds to (127.0.0.1:7734). The `af agent run` subcommand fetches its session detail from <DefaultAgentRunDaemonURL>/api/daemon/sessions/<id>.

Functions

func NewKitCmd

func NewKitCmd(ds func() afclient.DataSource) *cobra.Command

NewKitCmd returns a fresh `kit` Cobra command tree (list, show, install, enable, disable, verify, sources) targeting the local daemon. See kit.go for per-subcommand documentation.

func NewProviderCmd

func NewProviderCmd(ds func() afclient.DataSource) *cobra.Command

NewProviderCmd returns a fresh `provider` Cobra command tree (list, show) targeting the local daemon. See provider.go for per-subcommand documentation.

func NewRoutingCmd

func NewRoutingCmd(ds func() afclient.DataSource) *cobra.Command

NewRoutingCmd returns a fresh `routing` Cobra command tree (show, explain) targeting the local daemon. See routing.go for per-subcommand documentation.

func NewWorkareaCmd

func NewWorkareaCmd(ds func() afclient.DataSource) *cobra.Command

NewWorkareaCmd returns a fresh `workarea` Cobra command tree (list, show, restore, diff) targeting the local daemon. See workarea.go for per-subcommand documentation.

func RegisterCommands

func RegisterCommands(root *cobra.Command, cfg Config)

RegisterCommands adds the shared AgentFactory subcommands to the given root command. Optional local/debug surfaces are controlled by Config. The commands use cfg to resolve API clients and defaults.

This is the primary integration point for downstream CLIs that want to embed AgentFactory functionality under their own root command (e.g. `mycli agent list`, `mycli daemon status`, etc.).

Types

type AnalysisResult

type AnalysisResult struct {
	LinesScanned  int            `json:"linesScanned"`
	ErrorLines    int            `json:"errorLines"`
	Matches       []PatternMatch `json:"matches"`
	DraftedIssues []DraftedIssue `json:"draftedIssues"`
	AnalyzedAt    time.Time      `json:"analyzedAt"`
}

AnalysisResult is the top-level result produced by the analyze command.

type BranchCleanResult

type BranchCleanResult struct {
	Scanned int           `json:"scanned"`
	Deleted int           `json:"deleted"`
	Errors  []BranchError `json:"errors"`
}

BranchCleanResult holds per-branch cleanup stats.

type BranchError

type BranchError struct {
	Branch string `json:"branch"`
	Error  string `json:"error"`
}

BranchError records a failure deleting one branch.

type CleanupResult

type CleanupResult struct {
	DryRun    bool              `json:"dryRun"`
	Worktrees WorktreeResult    `json:"worktrees"`
	Branches  BranchCleanResult `json:"branches"`
}

CleanupResult is the JSON shape emitted by `af admin cleanup`.

type Config

type Config struct {
	// ClientFactory returns an afclient.DataSource for API calls.
	// Required.
	ClientFactory func() afclient.DataSource

	// DefaultURLFunc is a lazy URL resolution function (for flag-based callers).
	// Optional. Checked before DefaultURL.
	DefaultURLFunc func() string

	// DefaultURL is the fallback API base URL if DefaultURLFunc is nil.
	DefaultURL string

	// EnableDashboard registers the dashboard command when true.
	EnableDashboard bool

	// EnableLegacyWorkerFleet registers the legacy worker/fleet process
	// commands when true. These commands remain available to the standalone
	// OSS af binary for local debugging, but embedders should usually expose
	// daemon as the host lifecycle surface instead.
	EnableLegacyWorkerFleet bool

	// ProjectFunc returns the active project slug (or ID) used to scope
	// list endpoints that support filtering AND to populate the
	// `X-Rensei-Project` header on every request (see OrgFunc note).
	// Returning an empty string means fleet-wide (no scope), preserving
	// the default behavior. Optional. When nil, all commands behave
	// fleet-wide.
	ProjectFunc func() string

	// OrgFunc returns the active org id (or slug, or WorkOS org id)
	// the embedding binary wants every afcli-imported command to scope
	// to. When non-empty, the value is sent as `X-Rensei-Org` on every
	// HTTP request the wrapped ClientFactory produces.
	//
	// Why this matters: the platform's CLI user-token auth selects the
	// caller's org membership from the WorkOS access token's `org_id`
	// claim, which is frozen to whichever org the user happened to be
	// in at token-mint time. With multiple humans + agents on a single
	// host running across many orgs concurrently, that frozen claim
	// silently misroutes commands to the wrong org. Sending an explicit
	// `X-Rensei-Org` per invocation makes the scope authoritative
	// (after a server-side membership check) and removes the implicit
	// dependency on token state.
	//
	// Optional. When nil OR returns an empty string, no header is
	// sent and the server falls back to its own resolution (single-org
	// users keep working unchanged).
	OrgFunc func() string

	// HostBinaryVersion is the version string the embedding binary
	// reports (typically injected via -ldflags into the main package).
	// When non-empty, `daemon run` passes it to daemon.Options.Version
	// so /api/daemon/status reports the running binary's version
	// instead of agentfactory-tui's vendored package default. Empty
	// falls back to the daemon package's own Version var.
	HostBinaryVersion string
}

Config controls how af commands are wired into a parent CLI.

type DraftedIssue

type DraftedIssue struct {
	Signature   string   `json:"signature"`
	Title       string   `json:"title"`
	Description string   `json:"description"`
	Labels      []string `json:"labels"`
	// Posted is true when the issue was actually created in Linear.
	Posted     bool   `json:"posted"`
	Identifier string `json:"identifier,omitempty"`
	URL        string `json:"url,omitempty"`
}

DraftedIssue is a Linear issue draft derived from detected patterns.

type PatternMatch

type PatternMatch struct {
	SignatureID string                    `json:"signatureId"`
	Type        logsignatures.PatternType `json:"type"`
	Severity    logsignatures.Severity    `json:"severity"`
	Title       string                    `json:"title"`
	Occurrences int                       `json:"occurrences"`
	Examples    []string                  `json:"examples"`
}

PatternMatch records a single matched line.

type WorktreeError

type WorktreeError struct {
	Path  string `json:"path"`
	Error string `json:"error"`
}

WorktreeError records a failure removing one worktree.

type WorktreeResult

type WorktreeResult struct {
	Scanned  int             `json:"scanned"`
	Orphaned int             `json:"orphaned"`
	Cleaned  int             `json:"cleaned"`
	Skipped  int             `json:"skipped"`
	Errors   []WorktreeError `json:"errors"`
}

WorktreeResult holds per-worktree cleanup stats.