Skip to main content

CLI API

The Cli class is the core component that defines your custom CLI. This page documents the properties and methods of the Cli class.

Cli Class​

The Cli class is defined in hexagon/domain/cli.py and uses Pydantic for data validation.

class Cli(BaseModel):
    name: str
    command: str
    entrypoint: EntrypointConfig = EntrypointConfig()
    custom_tools_dir: Optional[str] = None
    plugins: List[str] = []
    options: Optional[dict] = None

Properties​

PropertyTypeDescriptionRequired
namestrThe display name of your CLIYes
commandstrThe command used to invoke your CLIYes
entrypointEntrypointConfigConfiguration for the CLI entrypointNo
custom_tools_dirOptional[str]Directory for custom tool implementationsNo
pluginsList[str]List of plugins to useNo
optionsOptional[dict]Runtime options (theme, updates, etc.)No

Property Details​

name: The display name shown in menus and help text.

command: The command users type to invoke your CLI (e.g., mycli means users run mycli).

entrypoint: Customizes the execution environment. See EntrypointConfig below.

custom_tools_dir: Path to a directory containing custom Python tools, relative to the config file. This directory is added to Python's sys.path, allowing tools to import custom modules.

plugins: List of plugin paths (relative to project directory). Plugins extend Hexagon with custom functionality. See Plugins Guide.

options: Runtime configuration options. See Runtime Options below.

EntrypointConfig Class​

The EntrypointConfig class defines how the CLI is executed.

class EntrypointConfig(BaseModel):
    shell: Optional[str] = None
    pre_command: Optional[str] = None
    environ: Dict[str, Any] = {}

Properties​

PropertyTypeDescriptionRequired
shellOptional[str]Custom shell to use for commands (default: sh)No
pre_commandOptional[str]Command to run before each tool executionNo
environDict[str, Any]Environment variables to setNo

Entrypoint Use Cases​

Custom Shell: Use a specific shell for command execution

entrypoint:
  shell: zsh  # Use zsh instead of sh

Environment Setup: Run setup commands before each tool

entrypoint:
  pre_command: source ~/.env && export PATH="$PATH:/custom/bin"

Environment Variables: Set variables for all tool executions

entrypoint:
  environ:
    NODE_ENV: production
    API_KEY: your-api-key
    DEBUG: "false"

Runtime Options​

The options property configures Hexagon's runtime behavior. Options can be set in three ways (in order of precedence):

  1. YAML configuration (cli.options)
  2. Environment variables (prefix with HEXAGON_)
  3. User storage (persisted settings)

Available Options​

cli:
  options:
    # UI Configuration
    theme: default                          # default, disabled, result_only
    hints_disabled: false                   # Disable hint messages

    # Update Configuration
    update_disabled: false                  # Disable hexagon framework updates
    cli_update_disabled: false              # Disable CLI project updates
    update_time_between_checks: 86400       # Update check interval (seconds)

    # Feature Configuration
    send_telemetry: false                   # Enable/disable telemetry
    disable_dependency_scan: false          # Disable dependency scanning
    cwd_tools_disabled: false               # Disable directory-specific tools

    # Storage Configuration
    config_storage_path: /custom/path       # Custom storage location

    # Keyboard Configuration
    keymap:
      create_dir: "c-p"                     # Custom keyboard shortcuts

Options Reference​

OptionTypeDefaultDescription
themestr"default"UI theme: default, disabled, result_only
update_disabledboolfalseDisable automatic hexagon framework updates
cli_update_disabledboolfalseDisable automatic CLI project updates
update_time_between_checksint86400Seconds between update checks (1 day)
hints_disabledboolfalseDisable helpful hint messages
cwd_tools_disabledboolfalseDisable loading hexagon_tools.yaml from current directory
send_telemetryboolfalseEnable anonymous usage telemetry
disable_dependency_scanboolfalseDisable dependency vulnerability scanning
config_storage_pathstrSystem defaultCustom path for user data storage
keymapdict{}Custom keyboard shortcut mappings

Environment Variable Equivalents​

All options can be set via environment variables by prefixing with HEXAGON_:

export HEXAGON_THEME=disabled
export HEXAGON_UPDATE_DISABLED=true
export HEXAGON_CLI_UPDATE_DISABLED=true
export HEXAGON_HINTS_DISABLED=true
export HEXAGON_CWD_TOOLS_DISABLED=true
export HEXAGON_SEND_TELEMETRY=false

Theme Options​

default: Full rich terminal output with colors, borders, and formatting

disabled: Minimal output without styling (useful for CI/CD)

result_only: Only show final results, hide intermediate messages

See the Runtime Options API for complete documentation.

Complete Example​

Here's a comprehensive example of a CLI configuration:

cli:
  name: Team CLI
  command: team
  custom_tools_dir: ./custom_tools
  plugins:
    - plugins/telemetry.py
    - plugins/authentication.py

  options:
    theme: default
    update_disabled: false
    cli_update_disabled: false
    hints_disabled: false
    cwd_tools_disabled: false

  entrypoint:
    shell: zsh
    pre_command: source ~/.env
    environ:
      NODE_ENV: production
      DEBUG: "false"

And here's how you might create a Cli instance programmatically:

from hexagon.domain.cli import Cli, EntrypointConfig

entrypoint = EntrypointConfig(
    shell="zsh",
    pre_command="source ~/.env",
    environ={
        "NODE_ENV": "production",
        "DEBUG": "false"
    }
)

cli = Cli(
    name="Team CLI",
    command="team",
    custom_tools_dir="./custom_tools",
    plugins=["plugins/telemetry.py", "plugins/authentication.py"],
    options={
        "theme": "default",
        "update_disabled": False,
        "hints_disabled": False
    },
    entrypoint=entrypoint
)

See Also​