Struct Cli 

pub struct Cli { /* private fields */ }

Main CLI structure for AGPM (Claude Code Package Manager).

This struct represents the root command and all its global options. It uses the clap derive API to automatically generate command-line parsing, help text, and validation. All options marked as global = true are available to all subcommands.

Design Philosophy

The CLI follows standard Unix conventions:

• Short options use single dashes (-v)
• Long options use double dashes (--verbose)
• Global options work with all subcommands
• Mutually exclusive options are validated automatically

Global Options

All subcommands inherit these global options:

• Verbosity control: --verbose and --quiet for output level
• Configuration: --config for custom config file paths
• UI control: --no-progress for automation-friendly output

Examples

# Basic command with global options
agpm --verbose install
agpm --quiet --no-progress list
agpm --config ./custom.toml validate

# Global options work with any subcommand
agpm --verbose install
agpm --quiet cache clean

Subcommand Structure

Commands are organized by functionality:

• Project management: install, update, add, remove
• Information: list, validate
• System: cache, config, upgrade

Integration Points

This CLI integrates with:

• CliConfig for dependency injection and testing
• Environment variables for runtime configuration
• Global and project-specific configuration files
• Cross-platform file system operations

Main CLI application structure for AGPM

This struct represents the top-level command-line interface for the Claude Code Package Manager. It handles global flags and delegates to subcommands for specific operations.

Implementations

impl Cli

pub async fn execute(self) -> Result<()>

Execute the CLI with default configuration.

This is the main entry point for CLI execution. It builds a configuration from the parsed command-line arguments and delegates to execute_with_config.

Process Flow

1. Configuration Building: Converts CLI arguments to CliConfig
2. Environment Setup: Applies configuration to process environment
3. Command Dispatch: Routes to the appropriate subcommand handler
4. Error Handling: Provides user-friendly error messages

Returns

• Ok(()) if the command executed successfully
• Err(anyhow::Error) if the command failed with details for user feedback

Examples

use agpm_cli::cli::Cli;
use clap::Parser;

let cli = Cli::parse(); // From command-line arguments
cli.execute().await?;

pub fn build_config(&self) -> CliConfig

Build a CliConfig from the parsed CLI arguments.

This method translates command-line flags into a structured configuration that can be applied to the environment or injected into tests.

Configuration Logic

• Verbose mode: Sets log level to “debug” for detailed output
• Quiet mode: Disables logging for automation-friendly output
• Default mode: Uses “info” level for normal operation
• Progress control: Honors --no-progress flag for animations
• Config path: Uses custom config file if specified

Validation

The CLI parser already handles mutual exclusion between --verbose and --quiet, so this method doesn’t need additional validation.

Returns

A CliConfig instance ready for environment application or testing.

Examples

use agpm_cli::cli::Cli;
use clap::Parser;

let cli = Cli::parse_from(&["agpm", "--verbose", "install"]);
let config = cli.build_config();
assert_eq!(config.log_level, Some("debug".to_string()));

pub async fn execute_with_config(self, config: CliConfig) -> Result<()>

Execute the CLI with a specific configuration for dependency injection.

This method enables testing and programmatic usage by accepting an external configuration instead of building one from CLI arguments. It’s the core execution method that all entry points eventually call.

Design Benefits

• Testability: Tests can inject custom configurations
• Flexibility: Programmatic usage without CLI parsing
• No Global State: Configuration passed explicitly, no environment variables
• Consistency: Single execution path for all scenarios

Arguments

• config - The configuration to pass to command execution

Execution Flow

1. Command Matching: Dispatches to the appropriate subcommand
2. Config Passing: Passes configuration to commands that need it
3. Async Execution: Awaits the async command execution
4. Error Propagation: Returns any errors for higher-level handling

Returns

• Ok(()) if the command completed successfully
• Err(anyhow::Error) if the command failed with context for debugging

Examples

use agpm_cli::cli::{Cli, CliConfig};
use clap::Parser;

let cli = Cli::parse_from(&["agpm", "install"]);
let mut config = CliConfig::new();
config.log_level = Some("trace".to_string());
config.no_progress = true;

cli.execute_with_config(config).await?;

Trait Implementations

impl Args for Cli

fn group_id() -> Option<Id>

Report the ArgGroup::id for this set of arguments

fn augment_args<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate Self via FromArgMatches::from_arg_matches_mut

fn augment_args_for_update<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate self via FromArgMatches::update_from_arg_matches_mut

impl CommandFactory for Cli

fn command<'b>() -> Command

Build a Command that can instantiate Self.

fn command_for_update<'b>() -> Command

Build a Command that can update self.

impl FromArgMatches for Cli

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

impl Parser for Cli

fn parse() -> Self

Parse from std::env::args_os(), exit on error.

fn try_parse() -> Result<Self, Error>

Parse from std::env::args_os(), return Err on error.

fn parse_from<I, T>(itr: I) -> Self

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Parse from iterator, exit on error.

fn try_parse_from<I, T>(itr: I) -> Result<Self, Error>

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Parse from iterator, return Err on error.

fn update_from<I, T>(&mut self, itr: I)

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Update from iterator, exit on error.

fn try_update_from<I, T>(&mut self, itr: I) -> Result<(), Error>

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Update from iterator, return Err on error.