CLI Integration

Modern CLI tools are evolving beyond static flag parsing. By integrating large language models directly into the command-line interface, developers gain an interactive assistant that understands project context, reads files, and generates structured output -- all within familiar terminal workflows.

Key integration patterns include:

• Prompt-as-argument: Pass natural language directly as a CLI argument, letting the model interpret intent alongside project context.
• Piped input: Stream data from other Unix tools (logs, diffs, build output) into the model via stdin, making AI composable with existing toolchains.
• Tool calling: The model can invoke sandboxed tools (file read/write, search, shell commands) to gather information or make changes, closing the loop between reasoning and action.
• Streaming output: Responses are streamed token-by-token to stdout, giving users immediate feedback and enabling downstream piping.

This architecture makes the AI agent a first-class Unix citizen -- it reads from stdin, writes to stdout, returns meaningful exit codes, and composes with |, >, and xargs just like any other tool.

A minimal Python CLI skeleton using Click with AI integration:

import click
import sys
from anthropic import Anthropic

client = Anthropic()

@click.group()
@click.option("--model", default="claude-sonnet-4-20250514", help="Model to use")
@click.pass_context
def cli(ctx, model):
    """AI-powered CLI assistant."""
    ctx.ensure_object(dict)
    ctx.obj["model"] = model

@cli.command()
@click.argument("prompt")
@click.option("--pipe", is_flag=True, help="Read from stdin")
@click.option("--output", type=click.Choice(["text", "json", "md"]),
              default="text")
@click.option("--context", multiple=True, help="Files to include")
def ask(prompt, pipe, output, context):
    """Ask the AI a question with optional context."""
    messages = []

    # Read piped input
    if pipe and not sys.stdin.isatty():
        stdin_data = sys.stdin.read()
        messages.append({
            "role": "user",
            "content": f"Input data:\n```\n{stdin_data}\n```\n\n{prompt}"
        })
    else:
        messages.append({"role": "user", "content": prompt})

    # Add file context
    for filepath in context:
        with open(filepath) as f:
            messages[0]["content"] += f"\n\nFile {filepath}:\n```\n{f.read()}\n```"

    # Stream the response
    with client.messages.stream(
        model=ctx.obj["model"],
        max_tokens=4096,
        messages=messages,
    ) as stream:
        for text in stream.text_stream:
            click.echo(text, nl=False)

    click.echo()  # Final newline

if __name__ == "__main__":
    cli()

This skeleton supports piped input, file context injection, output format selection, and streaming responses. Extend it with tool definitions for file operations, search, and shell execution.

Production CLI tools with AI integration should follow these patterns:

• Always stream responses token-by-token rather than waiting for the full completion. This provides immediate feedback and allows users to interrupt early.
• Use Server-Sent Events or chunked transfer encoding for HTTP-based implementations.
• Buffer partial tokens on word boundaries for cleaner display in terminals that don't handle partial UTF-8 well.

• Return meaningful exit codes: 0 for success, 1 for user errors, 2 for API failures, 3 for tool execution failures.
• Write error messages to stderr so they don't pollute piped output. Use click.echo(..., err=True).
• Implement exponential backoff with jitter for rate-limited API calls. Set sensible timeouts (30s for simple queries, 120s for agent tasks).
• Catch and surface tool execution errors gracefully -- the model should be able to retry with a different approach.

• Store API keys in environment variables (ANTHROPIC_API_KEY), never in config files or command history.
• Support a config file hierarchy: project-level .claude.json overrides user-level ~/.config/claude/config.json.
• Implement token refresh for OAuth-based setups. Cache tokens securely using OS keychain (macOS Keychain, Linux Secret Service, Windows Credential Manager).
• Validate credentials on startup and provide clear error messages with setup instructions when authentication fails.