CLIConfig Struct

The CLIConfig struct controls how your agent binary behaves in CLI mode. It's optional - if omitted, reasonable defaults are used.

type CLIConfig struct {
    AppName             string
    AppDescription      string
    HelpPreamble        string
    HelpEpilog          string
    EnvironmentVars     []string
    DefaultOutputFormat string
    DisableColors       bool
}

Configuration Fields

AppName

Type: string Default: Binary filename

Application name displayed in help text and version information.

CLIConfig: &agent.CLIConfig{
    AppName: "my-tool",
}

AppDescription

Type: string Default: Empty

One-line description shown in help header.

CLIConfig: &agent.CLIConfig{
    AppDescription: "AI-powered document analyzer with control plane integration",
}

HelpPreamble

Type: string Default: Empty

Text displayed before command list in help output. Use for setup instructions, warnings, or prerequisites.

CLIConfig: &agent.CLIConfig{
    HelpPreamble: `⚠️  IMPORTANT: Set OPENAI_API_KEY before running.
For best results, use GPT-4 model (default).`,
}

HelpEpilog

Type: string Default: Empty

Text displayed after command list in help output. Use for examples, links, or additional context.

CLIConfig: &agent.CLIConfig{
    HelpEpilog: `Examples:
  $ export OPENAI_API_KEY=sk-...
  $ ./my-tool --set input="analyze this"
  $ ./my-tool analyze --input-file document.pdf

Documentation: https://agentfield.ai/docs`,
}

EnvironmentVars

Type: []string Default: Empty

List of environment variables to document in help output. Each string should describe one variable.

CLIConfig: &agent.CLIConfig{
    EnvironmentVars: []string{
        "OPENAI_API_KEY (required) - Your OpenAI API key",
        "MODEL (optional) - AI model to use (default: gpt-4)",
        "TEMPERATURE (optional) - Response creativity 0.0-2.0 (default: 0.7)",
        "AGENTFIELD_URL (optional) - Control plane URL for server mode",
    },
}

DefaultOutputFormat

Type: string Default: "json"

Default output format when not specified by --output flag.

Options:

"json" - Pretty-printed JSON
"yaml" - YAML format
"text" - Plain text (best for simple string results)

CLIConfig: &agent.CLIConfig{
    DefaultOutputFormat: "text", // For human-readable output
}

DisableColors

Type: bool Default: false

Disable ANSI color codes in output. Useful for CI/CD environments or piping to files.

CLIConfig: &agent.CLIConfig{
    DisableColors: true,
}

Can also be controlled via NO_COLOR environment variable at runtime.

Complete Example

main.go

package main

import (
    "context"
    "log"
    "os"

    "github.com/Agent-Field/agentfield/sdk/go/agent"
)

func main() {
    a, err := agent.New(agent.Config{
        NodeID:        "ai-assistant",
        Version:       "1.0.0",
        AgentFieldURL: os.Getenv("AGENTFIELD_URL"), // Optional

        CLIConfig: &agent.CLIConfig{
            AppName:        "ai-assistant",
            AppDescription: "Intelligent CLI assistant powered by GPT-4",

            HelpPreamble: `⚠️  IMPORTANT: Set OPENAI_API_KEY before running.
For best results, use GPT-4 model (default).`,

            EnvironmentVars: []string{
                "OPENAI_API_KEY (required) - Your OpenAI API key",
                "MODEL (optional) - AI model to use (default: gpt-4)",
                "TEMPERATURE (optional) - Response creativity 0.0-2.0 (default: 0.7)",
                "AGENTFIELD_URL (optional) - Control plane URL for server mode",
            },

            HelpEpilog: `Examples:
  $ export OPENAI_API_KEY=sk-...
  $ ./ai-assistant --set question="Explain quantum computing"
  $ ./ai-assistant ask --set question="Write a poem" --set temperature=1.5

Server Mode:
  $ AGENTFIELD_URL=http://localhost:8080 ./ai-assistant serve

Documentation: https://agentfield.ai/docs
Report issues: https://github.com/your-org/ai-assistant/issues`,

            DefaultOutputFormat: "text",
            DisableColors:       false,
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    // Register reasoners...
    // (see CLI-Enabled Reasoners guide)

    if err := a.Run(context.Background()); err != nil {
        log.Fatal(err)
    }
}

Help Output

With the above configuration, running ./ai-assistant --help displays:

ai-assistant - Intelligent CLI assistant powered by GPT-4

⚠️  IMPORTANT: Set OPENAI_API_KEY before running.
For best results, use GPT-4 model (default).

Usage:
  ai-assistant [command] [flags]

Available Commands:
  ask (default)  Ask the AI a question
  serve          Start agent server and connect to control plane
  help           Show this help information
  version        Show version information

Flags:
  --set key=value      Set input parameter (repeatable)
  --input <json>       Provide input as JSON string
  --input-file <path>  Load input from JSON file
  --output <format>    Output format: json, yaml, text (default: text)
  --help               Show help information
  --version            Show version information

Environment Variables:
  OPENAI_API_KEY (required) - Your OpenAI API key
  MODEL (optional) - AI model to use (default: gpt-4)
  TEMPERATURE (optional) - Response creativity 0.0-2.0 (default: 0.7)
  AGENTFIELD_URL (optional) - Control plane URL for server mode

Examples:
  $ export OPENAI_API_KEY=sk-...
  $ ./ai-assistant --set question="Explain quantum computing"
  $ ./ai-assistant ask --set question="Write a poem" --set temperature=1.5

Server Mode:
  $ AGENTFIELD_URL=http://localhost:8080 ./ai-assistant serve

Documentation: https://agentfield.ai/docs
Report issues: https://github.com/your-org/ai-assistant/issues

Best Practices

Help Text

Be concise: Users scan help text quickly
Show examples: Real commands users can copy-paste
Highlight requirements: Use warnings for critical setup steps
Include links: Documentation, issues, community

Environment Variables

Document all variables: Even optional ones
Show defaults: Help users understand what happens without config
Mark required: Use "(required)" suffix for mandatory variables
Group logically: Control plane vars, AI vars, feature flags

Output Format

Text for humans: Use "text" for simple CLI tools
JSON for scripts: Use "json" for machine-readable output
YAML for config: Use "yaml" when output is configuration

Color Support

Enable by default: Colors improve readability
Respect NO_COLOR: Honor environment variable
Disable for CI: Set DisableColors: true when detecting CI environment

Runtime Override

Users can override CLI configuration at runtime:

# Override output format
./my-tool --output yaml --set input=data

# Disable colors
NO_COLOR=1 ./my-tool --set input=data

# Combine multiple overrides
NO_COLOR=1 ./my-tool --output json --set input=data

Next Steps

Function:duotone

CLI-Enabled Reasoners

Enable reasoners for CLI access with WithCLI()

TextAlignLeft:duotone

Output Formatting

Customize output with WithCLIFormatter()

Code:duotone

Examples

See complete working examples

CLI Configuration

CLI-Enabled Reasoners

Output Formatting

Examples