Go & Rust CLI Frameworks

package main

import (
	"encoding/json"
	"errors"
	"fmt"
	"os"

	"github.com/spf13/cobra"
)

const (
	exitUsage                = 2
	exitConfirmationRequired = 5
)

// exitError carries the exit code chosen by a command.
type exitError struct {
	code int
	msg  string
}

func (e *exitError) Error() string { return e.msg }

func newRoot() *cobra.Command {
	var asJSON bool

	root := &cobra.Command{
		Use:           "docsctl",
		Short:         "Search and publish this site's documentation.",
		Version:       "0.1.0",
		SilenceUsage:  true, // no usage dump on runtime errors
		SilenceErrors: true, // main prints errors itself, on stderr
	}
	root.PersistentFlags().BoolVar(&asJSON, "json", false, "Emit JSON on stdout.")

	search := &cobra.Command{
		Use:     "search QUERY",
		Short:   "Search the documentation.",
		Example: "  docsctl search kalman --component irurueta-statistics --json",
		Args:    cobra.ExactArgs(1),
		RunE: func(cmd *cobra.Command, args []string) error {
			payload := map[string]any{"schemaVersion": 1, "query": args[0], "total": 0, "results": []any{}}
			if asJSON {
				return json.NewEncoder(cmd.OutOrStdout()).Encode(payload) // data on stdout only
			}
			_, err := fmt.Fprintf(cmd.OutOrStdout(), "0 result(s) for %s\n", args[0])
			return err
		},
	}
	search.Flags().String("component", "", "Restrict to one component.")

	var dryRun, yes bool
	publish := &cobra.Command{
		Use:   "publish",
		Short: "Publish a component (destructive unless --dry-run).",
		RunE: func(cmd *cobra.Command, args []string) error {
			if dryRun {
				_, err := fmt.Fprintln(cmd.OutOrStdout(), `{"dryRun":true,"schemaVersion":1}`)
				return err
			}
			if !yes {
				return &exitError{exitConfirmationRequired,
					"docsctl: publish needs confirmation; re-run with --yes or use --dry-run."}
			}
			return nil
		},
	}
	publish.Flags().String("component", "", "Component to publish.")
	_ = publish.MarkFlagRequired("component")
	publish.Flags().BoolVar(&dryRun, "dry-run", false, "Show the plan only.")
	publish.Flags().BoolVarP(&yes, "yes", "y", false, "Assume yes for confirmations.")

	root.AddCommand(search, publish)
	return root
}

func main() {
	if err := newRoot().Execute(); err != nil {
		var ee *exitError
		if errors.As(err, &ee) {
			fmt.Fprintln(os.Stderr, ee.msg)
			os.Exit(ee.code)
		}
		// Cobra returns flag and argument errors from Execute before any RunE runs;
		// a real tool wraps unexpected RunE errors in an exitError with code 1.
		fmt.Fprintln(os.Stderr, "docsctl:", err)
		os.Exit(exitUsage)
	}
}

package main

import (
	"fmt"
	"os"
	"strings"

	tea "charm.land/bubbletea/v2"
)

type result struct{ ID, Title string } // "results" of `docsctl search --json -- kalman`

type model struct {
	results []result
	cursor  int
}

func (m model) Init() tea.Cmd { return nil }

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
	if key, ok := msg.(tea.KeyPressMsg); ok {
		switch key.String() {
		case "q", "ctrl+c":
			return m, tea.Quit
		case "up", "k":
			m.cursor = max(0, m.cursor-1)
		case "down", "j":
			m.cursor = min(len(m.results)-1, m.cursor+1)
		}
	}
	return m, nil
}

func (m model) View() tea.View {
	var b strings.Builder
	for i, r := range m.results {
		marker := " "
		if i == m.cursor {
			marker = ">"
		}
		fmt.Fprintf(&b, "%s %s  (%s)\n", marker, r.Title, r.ID)
	}
	b.WriteString("\nUp/down to move, q to quit.\n")
	return tea.NewView(b.String())
}

func isTerminal(f *os.File) bool {
	fi, err := f.Stat()
	return err == nil && fi.Mode()&os.ModeCharDevice != 0
}

func browse(results []result) int {
	if !isTerminal(os.Stdin) || !isTerminal(os.Stdout) { // never start a TUI for a pipe or an agent
		fmt.Fprintln(os.Stderr, "docsctl: browse needs a terminal; use `docsctl search --json -- QUERY` instead.")
		return 2
	}
	if _, err := tea.NewProgram(model{results: results}).Run(); err != nil {
		fmt.Fprintln(os.Stderr, "docsctl:", err)
		return 1
	}
	return 0
}

use std::io;
use std::process::ExitCode;

use clap::{Args, CommandFactory, Parser, Subcommand};
use clap_complete::Shell;

const CONFIRMATION_REQUIRED: u8 = 5;

/// Search and publish this site's documentation.
#[derive(Parser)]
#[command(name = "docsctl", version)]
struct Cli {
    /// Emit JSON on stdout.
    #[arg(long, global = true)]
    json: bool,

    #[command(subcommand)]
    command: Command,
}

#[derive(Subcommand)]
enum Command {
    /// Search the documentation.
    Search(SearchArgs),
    /// Publish a component (destructive unless --dry-run).
    Publish(PublishArgs),
    /// Print a shell completion script.
    Completion {
        #[arg(value_enum)]
        shell: Shell,
    },
}

#[derive(Args)]
struct SearchArgs {
    /// Words to look for.
    query: String,
    /// Restrict to one component.
    #[arg(long)]
    component: Option<String>,
}

#[derive(Args)]
struct PublishArgs {
    /// Component to publish.
    #[arg(long)]
    component: String,
    /// Show the plan only.
    #[arg(long)]
    dry_run: bool,
    /// Assume yes for confirmations.
    #[arg(long, short = 'y')]
    yes: bool,
}

fn main() -> ExitCode {
    let cli = Cli::parse(); // usage errors: message on stderr, exit code 2
    match cli.command {
        Command::Search(args) => {
            println!("{{\"query\":\"{}\",\"results\":[],\"schemaVersion\":1,\"total\":0}}", args.query);
            ExitCode::SUCCESS
        }
        Command::Publish(args) if args.dry_run => {
            println!("{{\"dryRun\":true,\"schemaVersion\":1}}");
            ExitCode::SUCCESS
        }
        Command::Publish(args) if !args.yes => {
            eprintln!("docsctl: publish needs confirmation; re-run with --yes or use --dry-run.");
            ExitCode::from(CONFIRMATION_REQUIRED)
        }
        Command::Publish(_) => ExitCode::SUCCESS,
        Command::Completion { shell } => {
            clap_complete::generate(shell, &mut Cli::command(), "docsctl", &mut io::stdout());
            ExitCode::SUCCESS
        }
    }
}

use crossterm::event;

fn main() -> std::io::Result<()> {
    ratatui::run(|mut terminal| {
        loop {
            terminal.draw(|frame| frame.render_widget("Hello World!", frame.area()))?;
            if event::read()?.is_key_press() {
                break Ok(());
            }
        }
    })
}

use std::process::Command;

use rig::completion::Prompt;
use rig::prelude::*;
use rig::providers::anthropic;
use rig::tool::{Tool, ToolContext};
use serde::Deserialize;
use serde_json::json;

const DOCSCTL: &str = "/usr/local/bin/docsctl"; // absolute path, not a PATH lookup

#[derive(Deserialize)]
struct SearchArgs {
    query: String,
}

#[derive(Debug, thiserror::Error)]
enum DocsctlError {
    #[error("query must be 1-200 characters")]
    InvalidQuery,
    #[error("could not run docsctl: {0}")]
    Io(#[from] std::io::Error),
    #[error("docsctl exited with {code:?}: {stderr}")]
    Failed { code: Option<i32>, stderr: String },
}

struct DocsctlSearch;

impl Tool for DocsctlSearch {
    const NAME: &'static str = "docsctl_search";
    type Args = SearchArgs;
    type Output = String; // the JSON document printed by docsctl
    type Error = DocsctlError;

    fn description(&self) -> String {
        "Search this site's documentation and return docsctl's JSON result.".to_string()
    }

    fn parameters(&self) -> serde_json::Value {
        json!({
            "type": "object",
            "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 200 } },
            "required": ["query"]
        })
    }

    async fn call(&self, _context: &mut ToolContext, args: Self::Args) -> Result<Self::Output, Self::Error> {
        if args.query.trim().is_empty() || args.query.len() > 200 {
            return Err(DocsctlError::InvalidQuery);
        }
        let output = Command::new(DOCSCTL)                         // an argv array, never a shell
            .args(["search", "--json", "--no-input", "--"])        // "--" before the user operand
            .arg(&args.query)
            .env_clear()
            .env("PATH", "/usr/bin:/bin")
            .output()?;
        if !output.status.success() {
            return Err(DocsctlError::Failed {
                code: output.status.code(),
                stderr: String::from_utf8_lossy(&output.stderr).into_owned(),
            });
        }
        Ok(String::from_utf8_lossy(&output.stdout).into_owned())
    }
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let agent = anthropic::Client::from_env()?                     // reads the API key from the environment
        .agent(anthropic::completion::CLAUDE_SONNET_4_6)
        .preamble("Answer questions about this site's documentation. Call docsctl_search before answering.")
        .tool(DocsctlSearch)
        .default_max_turns(4)
        .build();
    let answer = agent.prompt("What does the Kalman filter page cover?").await?;
    println!("{answer}");
    Ok(())
}