Go ● stable v1.0.2

Three adapters cover the major Go CLI frameworks: spf13/cobra, urfave/cli v2, and urfave/cli v3. Each adapter exposes the same conceptual operations with framework-idiomatic signatures.

cobra adapter

Import path: github.com/murli-cli/murli-go/cobra

urfave/cli v2 adapter

Import path: github.com/murli-cli/murli-go/cli/v2

urfave/cli v3 adapter

Import path: github.com/murli-cli/murli-go/cli/v3

Writer

Package: github.com/murli-cli/murli-go

The Writer is the primary output surface. Obtain one via the adapter’s NewWriter in every handler. Do not construct one directly in normal use.

Constructor

func NewWriter(stdout, stderr io.Writer, agentMode bool, opts ...WriterOption) *Writer

Use the adapter’s NewWriter in handlers. The bare constructor is for testing or building custom adapters.

WriterOption functions

Output methods

State methods

OutputFormat constants

ProgressEvent struct

type ProgressEvent struct {
    Stage   string  `json:"stage,omitempty"`
    Current int     `json:"current,omitempty"`
    Total   int     `json:"total,omitempty"`
    Percent float64 `json:"percent,omitempty"`
    EtaMs   int64   `json:"eta_ms,omitempty"`
    Message string  `json:"message,omitempty"`
}

Logger

Package: github.com/murli-cli/murli-go

The Logger writes diagnostic output to stderr with consecutive line deduplication. w.Log() and w.Progress() use an internal logger. Use NewLogger directly only when building outside a standard handler context.

AgentError

Package: github.com/murli-cli/murli-go

Constructors

For other exit codes, construct an AgentError directly:

w.WriteError(&murli.AgentError{
    Code:        murli.ExitNotFound,
    ErrorType:   "not_found",
    Message:     "index file does not exist",
    Suggestion:  "Run `mytool index build` to create it.",
    Recoverable: true,
})

AgentError fields

Metadata

Package: github.com/murli-cli/murli-go

Pass to the adapter’s Annotate function. All fields are optional.

type Metadata struct {
    AgentDescription string
    WhenToUse        string
    Idempotent       bool
    Mutating         bool
    Arguments        []ArgumentMetadata
    Returns          *ReturnSchema
    Examples         []Example
    FlagAnnotations  map[string]FlagAnnotation
    DryRunnable      bool
    Destructive      bool
}

ArgumentMetadata

type ArgumentMetadata struct {
    Name        string `json:"name"`
    Type        string `json:"type"`
    Required    bool   `json:"required"`
    Description string `json:"description"`
}

ReturnSchema

type ReturnSchema struct {
    Type         string          `json:"type"`
    Description  string          `json:"description"`
    Shape        map[string]any  `json:"shape,omitempty"`
    OutputSchema json.RawMessage `json:"output_schema,omitempty"`
}

Example

type Example struct {
    Command          string `json:"command"`
    Description      string `json:"description,omitempty"`
    ExpectedExitCode int    `json:"expected_exit_code,omitempty"`
}

Profiles

Package: github.com/murli-cli/murli-go

The profile subcommand handles profile management automatically. Use the ProfileStore API directly only when you need programmatic access to profiles outside a command handler.

Profile struct

type Profile struct {
    Flags map[string]string `json:"flags"`
}

type ProfileStore struct {
    Default  string             `json:"default,omitempty"`
    Profiles map[string]Profile `json:"profiles"`
}

Utilities

Package: github.com/murli-cli/murli-go

CheckConventions

Requires -tags murlidev. The function is a no-op stub in release builds.

func CheckConventions(commandNames, flagNames []string, w io.Writer) int

Checks command and flag names against the conventional vocabulary. Writes advisory warnings to w for non-standard names. Returns the count of issues found. Does not modify any state. Use in tests or CI to enforce naming standards.

Non-standard verbs flagged (with suggested replacement): fetch→get, info→get, retrieve→get, show-all→list, remove→delete, rm→delete, add→create, edit→update, modify→update.

Non-standard flags flagged: skip-confirmations→force, silent→quiet, preview→dry-run, format→output.

FormatAgentsMD

func FormatAgentsMD(out DescribeOutput) string

Generates an AGENTS.md stub from a DescribeOutput. Produces a Markdown document that lists each command, its description, flags, and examples. Intended as a starting point for agent-facing documentation.

Version constants