### Installing Hexagon CLI

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/getting-started/quick-start.md

This command initiates the Hexagon CLI installation process. After running, the user will be prompted to select the `my-cli.yaml` configuration file to install the defined CLI.

```bash
hexagon
```

--------------------------------

### Running the Hexagon CLI

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/getting-started/quick-start.md

This command executes the newly installed Hexagon CLI, 'My First CLI'. It displays the defined tools, allowing the user to select and run them using arrow keys.

```bash
mfc
```

--------------------------------

### Verifying Hexagon Installation (Bash)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/getting-started/installation.md

This command verifies the successful installation of Hexagon by displaying its currently installed version. A version number indicates a correct installation.

```bash
hexagon --version
```

--------------------------------

### Example CLI Configuration in YAML

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/cli.md

This YAML snippet provides an example configuration for a Hexagon CLI. It defines the CLI's `name`, `command`, `custom_tools_dir`, `plugins`, and detailed `entrypoint` settings including `shell`, `pre_command`, and environment variables, demonstrating a typical declarative setup.

```yaml
cli:
  name: Team CLI
  command: team
  custom_tools_dir: ./custom_tools
  plugins:
    - my_plugin
  entrypoint:
    shell: /bin/bash
    pre_command: source .env
    environ:
      DEBUG: "true"
```

--------------------------------

### Running Hexagon CLI (Bash)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/getting-started/installation.md

This command launches the Hexagon command-line interface. Upon first execution, it typically presents the default CLI, which includes tools for creating and managing custom CLIs.

```bash
hexagon
```

--------------------------------

### Installing Dependencies with Yarn

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/README.md

This command installs all necessary project dependencies using Yarn. It should be run once after cloning the repository to set up the development environment.

```Shell
$ yarn
```

--------------------------------

### Installing Hexagon with pipx (Bash)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/getting-started/installation.md

This command installs the Hexagon CLI tool using pipx, which ensures the installation is isolated from other Python packages. It installs the latest stable version along with its dependencies.

```bash
pipx install hexagon
```

--------------------------------

### Example: Simple Web Tool Configuration (YAML)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/actions/web.md

A practical example of configuring a straightforward web tool named 'docs' that opens team documentation. It defines an alias, a description, and environment-specific URLs for development and production.

```YAML
- name: docs
  alias: d
  long_name: Documentation
  description: Open team documentation
  type: web
  action: open_link
  envs:
    dev: https://docs-dev.example.com
    prod: https://docs.example.com
```

--------------------------------

### Registering Hooks within a Hexagon Plugin's Setup Function (Python)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/advanced/hooks.md

This example illustrates the typical way to register Hexagon hooks within a plugin. The `setup` function, which is called when the plugin is loaded, is used to register `my_start_function` and `my_end_function` with the `start` and `end` hooks, respectively. This ensures that the custom logic defined in these functions is executed as part of the plugin's integration with the Hexagon CLI lifecycle.

```Python
# my_plugin.py
from hexagon.support.hooks import HexagonHooks

def setup(cli, tools, envs):
    HexagonHooks.start.register(my_start_function)
    HexagonHooks.end.register(my_end_function)

def my_start_function():
    print("Hexagon is starting...")

def my_end_function():
    print("Hexagon is ending...")
```

--------------------------------

### Creating a Web Tool Example in Python

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/tool.md

This example demonstrates how to instantiate an `ActionTool` configured as a web tool. It defines a 'docs' tool that opens documentation links, with different URLs for 'dev' and 'prod' environments, showcasing the use of `name`, `alias`, `long_name`, `description`, `type`, `action`, and `envs` properties.

```python
from hexagon.domain.tool import ActionTool, ToolType

web_tool = ActionTool(
    name="docs",
    alias="d",
    long_name="Documentation",
    description="Open team documentation",
    type=ToolType.web,
    action="open_link",
    envs={
        "dev": "https://docs-dev.example.com",
        "prod": "https://docs.example.com"
    }
)
```

--------------------------------

### Registering a Simple Start Hook Function - Python

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/support/hooks.md

This example illustrates how to define a simple Python function and register it with the `start` hook. The function `my_start_function` will be executed when Hexagon begins its operation, printing a message to the console.

```Python
from hexagon.support.hooks import HexagonHooks

def my_start_function():
    print("Hexagon is starting...")

# Register the function with the start hook
HexagonHooks.start.register(my_start_function)
```

--------------------------------

### Applying Default Theme Example (Bash)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/guides/theming.md

This example shows the command to run 'mycli' with the 'default' theme by setting the HEXAGON_THEME environment variable. This results in a colorful interface with visual hierarchy and decorations, providing a rich CLI experience.

```bash
HEXAGON_THEME=default mycli
```

--------------------------------

### Configuring Multi-line Shell Commands in Hexagon CLI (YAML)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/guides/tool-types.md

This snippet illustrates configuring a shell tool that executes multiple commands sequentially. The 'setup' tool uses a list of strings for its action property, allowing for complex, multi-step operations like 'echo', 'npm install', and 'npm run build'.

```yaml
- name: setup
  alias: s
  long_name: Setup Project
  description: Set up the project
  type: shell
  action:
    - "echo 'Setting up project...'" 
    - "npm install"
    - "npm run build"
```

--------------------------------

### Example: Web Tool Configuration with Multiple Parameters (YAML)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/actions/web.md

An example demonstrating a web tool for opening JIRA issues. It uses multiple parameters, `{project}` and `{issue}`, in the URL, which will prompt the user for specific project and issue identifiers.

```YAML
- name: jira
  alias: j
  long_name: JIRA Issue
  description: Open a JIRA issue
  type: web
  action: open_link
  envs:
    dev: https://jira-dev.example.com/browse/{project}-{issue}
    prod: https://jira.example.com/browse/{project}-{issue}
```

--------------------------------

### Basic Hexagon CLI Configuration Example (YAML)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/getting-started/configuration.md

This snippet illustrates the basic structure of a Hexagon CLI configuration file. It defines the CLI's name and command, sets up 'development' and 'production' environments, and includes a 'web' type tool that opens different links based on the environment.

```YAML
cli:
  name: My CLI
  command: mycli
  custom_tools_dir: ./custom_tools
  plugins: []

envs:
  - name: development
    alias: dev
  - name: production
    alias: prod

tools:
  - name: tool1
    alias: t1
    type: web
    action: open_link
    envs:
      development: https://dev.example.com
      production: https://example.com
```

--------------------------------

### Executing a Hexagon CLI Tool with a Specific Environment

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/getting-started/quick-start.md

This command executes the 'google' tool within the 'My First CLI', explicitly setting the environment to 'dev'. This ensures the tool's action (e.g., opening a link) uses the 'dev' specific configuration.

```bash
mfc g -e dev
```

--------------------------------

### Running Hexagon for CLI Installation (Bash)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/guides/creating-a-cli.md

This bash command initiates the Hexagon application, which provides an interactive interface for managing and installing CLIs. After running this command, users can select options like 'Install CLI' to set up their custom CLI based on a configuration file.

```bash
hexagon
```

--------------------------------

### Creating a Basic Hexagon Plugin Setup Function

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/guides/plugins.md

This Python snippet demonstrates the basic structure of a Hexagon plugin. A plugin is a Python module containing a `setup` function, which Hexagon calls upon loading the plugin. This function receives `cli`, `tools`, and `envs` arguments for initialization.

```python
# my_plugin.py

def setup(cli, tools, envs):
    """Set up the plugin.
    
    Args:
        cli: The CLI configuration
        tools: The list of tools
        envs: The list of environments
    """
    print("Setting up my_plugin...")
    # Your plugin initialization code here
```

--------------------------------

### Creating a Shell Tool Example in Python

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/tool.md

This example illustrates the creation of an `ActionTool` configured as a shell tool. It defines a 'deploy' tool that executes a shell script, demonstrating how to set `name`, `alias`, `long_name`, `description`, `type`, and `action` for command-line operations.

```python
from hexagon.domain.tool import ActionTool, ToolType

shell_tool = ActionTool(
    name="deploy",
    alias="dep",
    long_name="Deploy Service",
    description="Deploy the service",
    type=ToolType.shell,
    action="./scripts/deploy.sh"
)
```

--------------------------------

### Starting Local Development Server with Yarn

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/README.md

This command initiates a local development server, typically opening the project in a web browser. It enables live reloading, reflecting code changes instantly without server restarts, which is ideal for active development.

```Shell
$ yarn start
```

--------------------------------

### Implementing an Authentication Plugin for Hexagon

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/guides/plugins.md

This snippet provides an example of an authentication plugin for Hexagon. It registers a `check_auth` function to run at the start of Hexagon's lifecycle, which checks user authentication status and prompts for login if necessary. This demonstrates how plugins can enforce prerequisites before CLI operations.

```python
# auth_plugin.py
from hexagon.support.hooks import HexagonHooks

def setup(cli, tools, envs):
    HexagonHooks.start.register(check_auth)

def check_auth():
    # Check if the user is authenticated
    if not is_authenticated():
        print("You are not authenticated. Please log in.")
        login()

def is_authenticated():
    # Check if the user is authenticated
    # This is just an example, implement your own authentication logic
    return False

def login():
    # Implement your login logic
    print("Logging in...")
```

--------------------------------

### Executing a Hexagon CLI Tool by Alias

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/getting-started/quick-start.md

This command directly executes the 'google' tool (aliased as 'g') within the 'My First CLI'. This bypasses the interactive tool selection menu.

```bash
mfc g
```

--------------------------------

### Defining a Hexagon CLI Configuration in YAML

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/getting-started/quick-start.md

This YAML configuration file defines a Hexagon CLI named 'My First CLI' with the command 'mfc'. It includes two environments ('dev', 'prod') and two tools: 'google' (a web tool to open links) and 'hello' (a shell tool to print a greeting). The 'google' tool has environment-specific links.

```yaml
cli:
  name: My First CLI
  command: mfc

envs:
  - name: dev
    alias: d
  - name: prod
    alias: p

tools:
  - name: google
    alias: g
    long_name: Google Search
    description: Open Google search
    type: web
    action: open_link
    envs:
      dev: https://google.com?q=dev
      prod: https://google.com

  - name: hello
    alias: h
    long_name: Hello World
    description: Print a greeting
    type: shell
    action: echo "Hello, World!"
```

--------------------------------

### Creating a Logging Plugin for Hexagon

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/guides/plugins.md

This example illustrates a Hexagon plugin that integrates basic logging functionality. It configures Python's `logging` module to write to a file and registers `log_start` and `log_end` functions with Hexagon's `start` and `end` hooks, respectively, to log lifecycle events.

```python
# logging_plugin.py
import logging
from hexagon.support.hooks import HexagonHooks

def setup(cli, tools, envs):
    # Configure logging
    logging.basicConfig(filename="hexagon.log", level=logging.INFO)
    
    # Register hooks
    HexagonHooks.start.register(log_start)
    HexagonHooks.end.register(log_end)

def log_start():
    logging.info("Hexagon started")

def log_end():
    logging.info("Hexagon ended")
```

--------------------------------

### Example: Web Tool Configuration with Single Parameter (YAML)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/actions/web.md

This example shows a web tool named 'search' configured to perform searches. It includes a `{query}` parameter in its URLs, allowing the user to input a search term when the tool is executed.

```YAML
- name: search
  alias: s
  long_name: Search
  description: Search for something
  type: web
  action: open_link
  envs:
    dev: https://search-dev.example.com?q={query}
    prod: https://search.example.com?q={query}
```

--------------------------------

### Hexagon CLI Configuration Example - YAML

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/intro.md

This YAML configuration defines a basic Hexagon CLI, including its name, command, environments (dev, prod), and two tools: 'docs' (a web link) and 'deploy' (a shell script). It demonstrates how to configure custom tools, environments, and actions within Hexagon, showcasing the simplicity of defining CLI behavior.

```YAML
cli:
  custom_tools_dir: .  # relative to this file
  name: Team CLI
  command: team

envs:
  - name: dev
    alias: d
  - name: prod
    alias: p

tools:
  - name: docs
    alias: d
    long_name: Documentation
    description: Open team documentation
    type: web
    envs:
      dev: https://docs-dev.example.com
      prod: https://docs.example.com
    action: open_link

  - name: deploy
    alias: dep
    long_name: Deploy Service
    type: shell
    action: ./scripts/deploy.sh
```

--------------------------------

### Starting Docusaurus Site with Specific Locale (Bash)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/tutorial-extras/translate-your-site.md

This command starts the Docusaurus development server, specifically loading the site with the 'fr' (French) locale. This allows developers to preview the translated content during development.

```Bash
npm run start -- --locale fr
```

--------------------------------

### Registering Hooks in a Hexagon Plugin - Python

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/support/hooks.md

This code demonstrates how to register Hexagon hooks within a plugin's `setup` function. The `setup` function is the entry point for plugin initialization, making it an ideal place to register lifecycle hooks like `start` and `end` for custom plugin logic.

```Python
# my_plugin.py
from hexagon.support.hooks import HexagonHooks

def setup(cli, tools, envs):
    HexagonHooks.start.register(my_start_function)
    HexagonHooks.end.register(my_end_function)

def my_start_function():
    print("Hexagon is starting...")

def my_end_function():
    print("Hexagon is ending...")
```

--------------------------------

### Function Demonstrating Basic Output and Success Logging - Python

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/support/output.md

This example provides a Python function, `my_function`, that utilizes the `log` object to indicate the start and successful completion of an operation. It showcases `log.info` for initial messages and `log.success` for confirming a successful outcome, returning a list of results. This pattern is useful for providing clear feedback on function execution.

```Python
from hexagon.support.output.printer import log

def my_function():
    log.info("Starting operation...")
    
    # Your logic here
    
    log.success("Operation completed successfully")
    return ["Result 1", "Result 2"]
```

--------------------------------

### Checking Python Version (Bash)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/getting-started/installation.md

This command checks the installed Python version on your system. Hexagon requires Python 3.9 or higher as a prerequisite for installation and operation.

```bash
python --version
```

--------------------------------

### Executing a Hexagon CLI Tool with an Environment Alias

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/getting-started/quick-start.md

Similar to specifying the full environment name, this command executes the 'google' tool within the 'My First CLI', using the 'dev' environment's alias 'd'. This provides a shorthand for environment selection.

```bash
mfc g -e d
```

--------------------------------

### Implementing a Logging Plugin with Hexagon Hooks (Python)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/advanced/hooks.md

This example showcases a `logging_plugin.py` that uses Hexagon hooks to log the start and end times of the CLI execution. It configures basic file logging and registers `log_start` and `log_end` functions with the `start` and `end` hooks, respectively. This allows for automatic logging of CLI lifecycle events, including the total execution duration, without modifying Hexagon's core.

```Python
# logging_plugin.py
import logging
import time
from hexagon.support.hooks import HexagonHooks

def setup(cli, tools, envs):
    # Configure logging
    logging.basicConfig(filename="hexagon.log", level=logging.INFO)
    
    # Register hooks
    HexagonHooks.start.register(log_start)
    HexagonHooks.end.register(log_end)

def log_start():
    global start_time
    start_time = time.time()
    logging.info(f"Hexagon started at {time.strftime('%Y-%m-%d %H:%M:%S')}")

def log_end():
    end_time = time.time()
    duration = end_time - start_time
    logging.info(f"Hexagon ended at {time.strftime('%Y-%m-%d %H:%M:%S')}")
    logging.info(f"Duration: {duration:.2f} seconds")
```

--------------------------------

### Creating a Group Tool Example in Python

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/tool.md

This example demonstrates how to create a `GroupTool` that organizes other `ActionTool` instances. It defines 'provision' and 'teardown' shell tools and then groups them under an 'infra' tool, showcasing how to nest tools and use `name`, `alias`, `long_name`, `description`, `type`, and the `tools` list property.

```python
from hexagon.domain.tool import GroupTool, ActionTool, ToolType

provision_tool = ActionTool(
    name="provision",
    alias="p",
    long_name="Provision Resources",
    type=ToolType.shell,
    action="./scripts/provision.sh"
)

teardown_tool = ActionTool(
    name="teardown",
    alias="t",
    long_name="Teardown Resources",
    type=ToolType.shell,
    action="./scripts/teardown.sh"
)

group_tool = GroupTool(
    name="infra",
    alias="i",
    long_name="Infrastructure",
    description="Infrastructure tools",
    type=ToolType.group,
    tools=[provision_tool, teardown_tool]
)
```

--------------------------------

### Implementing an Authentication Plugin with Hexagon Hooks - Python

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/support/hooks.md

This snippet provides an example of an authentication plugin that uses the `start` hook to check user authentication before CLI execution. If authentication fails, it raises a `HexagonError` to halt the process, ensuring secure access.

```Python
# auth_plugin.py
from hexagon.support.hooks import HexagonHooks
from hexagon.domain.hexagon_error import HexagonError

def setup(cli, tools, envs):
    HexagonHooks.start.register(check_auth)

def check_auth():
    # Check if the user is authenticated
    if not is_authenticated():
        # Prompt for authentication
        if not authenticate():
            # If authentication fails, raise an error to stop execution
            raise HexagonError("Authentication failed")

def is_authenticated():
    # Check if the user is authenticated
    # This is just an example, implement your own authentication logic
    return False

def authenticate():
    # Implement your authentication logic
    print("Please enter your credentials:")
    username = input("Username: ")
    password = input("Password: ")
    
    # Validate credentials
    # This is just an example, implement your own validation logic
    return username == "admin" and password == "password"
```

--------------------------------

### Compiling Example Spanish PO File (Bash)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/advanced/internationalization.md

This command compiles the example Spanish `.po` file into its corresponding binary `.mo` file. This step makes the Spanish translations available for the Hexagon CLI to use at runtime.

```Bash
msgfmt -o locales/es/LC_MESSAGES/hexagon.mo locales/es/LC_MESSAGES/hexagon.po
```

--------------------------------

### Testing a Hexagon CLI Command (Bash)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/guides/creating-a-cli.md

This bash command executes the custom CLI, 'team', which was previously configured and installed using Hexagon. Running this command allows users to verify that all defined tools and environments within the CLI function as expected, ensuring proper setup and accessibility.

```bash
team
```

--------------------------------

### Installing Pipenv for Development

Source: https://github.com/lt-mayonesa/hexagon/blob/main/README.md

This command installs `pipenv`, a dependency management tool for Python projects. It is a prerequisite for setting up the development environment for Hexagon, ensuring consistent project dependencies.

```bash
pip install pipenv
```

--------------------------------

### Defining Basic CLI Configuration in Hexagon (YAML)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/guides/creating-a-cli.md

This YAML snippet defines the foundational structure for a Hexagon CLI, including its name, command, an optional custom tools directory, and a list of environments (development, staging, production) with their aliases. It serves as the starting point for configuring a new CLI.

```yaml
cli:
  name: Team CLI
  command: team
  custom_tools_dir: ./custom_tools  # Optional

envs:
  - name: development
    alias: dev
  - name: staging
    alias: stg
  - name: production
    alias: prod

tools:
  # Your tools will go here
```

--------------------------------

### Installing Hexagon CLI

Source: https://github.com/lt-mayonesa/hexagon/blob/main/README.md

This command installs the Hexagon command-line interface globally using `pipx`. `pipx` ensures that the CLI is installed in an isolated environment, preventing dependency conflicts with other Python packages.

```bash
pipx install hexagon
```

--------------------------------

### Registering Basic Hooks in Hexagon Python

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/advanced/hooks.md

This snippet demonstrates how to register functions with Hexagon's `start` and `end` hooks. It shows the basic syntax for importing `HexagonHooks` and using its `register` method to associate custom functions with specific CLI lifecycle events. The `my_start_function` and `my_end_function` are simple examples of functions that would execute at the beginning and end of the Hexagon CLI process, respectively.

```Python
from hexagon.support.hooks import HexagonHooks

# Register a function with the start hook
HexagonHooks.start.register(my_start_function)

# Register a function with the end hook
HexagonHooks.end.register(my_end_function)

def my_start_function():
    print("Hexagon is starting...")

def my_end_function():
    print("Hexagon is ending...")
```

--------------------------------

### Implementing a Logging Plugin with Hexagon Hooks - Python

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/support/hooks.md

This example showcases a logging plugin that uses Hexagon hooks to log the start and end times of the CLI execution. It configures basic logging and registers `log_start` and `log_end` functions with the respective hooks to record session duration.

```Python
# logging_plugin.py
import logging
import time
from hexagon.support.hooks import HexagonHooks

def setup(cli, tools, envs):
    # Configure logging
    logging.basicConfig(filename="hexagon.log", level=logging.INFO)
    
    # Register hooks
    HexagonHooks.start.register(log_start)
    HexagonHooks.end.register(log_end)

def log_start():
    global start_time
    start_time = time.time()
    logging.info(f"Hexagon started at {time.strftime('%Y-%m-%d %H:%M:%S')}")

def log_end():
    end_time = time.time()
    duration = end_time - start_time
    logging.info(f"Hexagon ended at {time.strftime('%Y-%m-%d %H:%M:%S')}")
    logging.info(f"Duration: {duration:.2f} seconds")
```

--------------------------------

### Implementing an Authentication Plugin with Hexagon Hooks (Python)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/advanced/hooks.md

This example demonstrates an `auth_plugin.py` that integrates an authentication mechanism using Hexagon's `start` hook. The `check_auth` function is registered to run at CLI startup, verifying user authentication. If the user is not authenticated, it prompts for credentials and, if authentication fails, raises a `HexagonError` to halt CLI execution. This illustrates how hooks can enforce security policies before any tool execution.

```Python
# auth_plugin.py
from hexagon.support.hooks import HexagonHooks
from hexagon.domain.hexagon_error import HexagonError

def setup(cli, tools, envs):
    HexagonHooks.start.register(check_auth)

def check_auth():
    # Check if the user is authenticated
    if not is_authenticated():
        # Prompt for authentication
        if not authenticate():
            # If authentication fails, raise an error to stop execution
            raise HexagonError("Authentication failed")

def is_authenticated():
    # Check if the user is authenticated
    # This is just an example, implement your own authentication logic
    return False

def authenticate():
    # Implement your authentication logic
    print("Please enter your credentials:")
    username = input("Username: ")
    password = input("Password: ")
    
    # Validate credentials
    # This is just an example, implement your own validation logic
    return username == "admin" and password == "password"
```

--------------------------------

### Applying Result Only Theme Example (Bash)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/guides/theming.md

This snippet demonstrates how to run 'mycli' with the 'result_only' theme by setting the HEXAGON_THEME environment variable. This theme is ideal for scripting and automation, as it only displays the final result logs, minimizing output noise.

```bash
HEXAGON_THEME=result_only mycli
```

--------------------------------

### Configuring Environments in YAML

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/env.md

This YAML example demonstrates how to define multiple environment configurations. Each entry includes the environment's name, an optional alias, a long name, and a description, mirroring the properties of the `Env` class. These configurations are typically loaded by the Hexagon CLI to manage different operational contexts.

```yaml
envs:
  - name: development
    alias: dev
    long_name: Development Environment
    description: Used for local development
  - name: staging
    alias: stg
    long_name: Staging Environment
    description: Used for testing before production
  - name: production
    alias: prod
    long_name: Production Environment
    description: Live production environment
```

--------------------------------

### Running Hexagon in Development Mode

Source: https://github.com/lt-mayonesa/hexagon/blob/main/README.md

These commands initiate a development shell, install Hexagon's development dependencies using `pipenv`, and then execute the Hexagon application. This sequence is essential for local development and testing of the Hexagon project.

```bash
# start a shell
pipenv shell
# install hexagon dependencies
pipenv install --dev
# run it
python -m hexagon
```

--------------------------------

### Defining Command-Line Arguments with Hexagon Python

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/advanced/prompting.md

This snippet demonstrates how to define command-line arguments for Hexagon tools using a class that inherits from `ToolArgs`. It shows examples of a required positional argument (`PositionalArg`), an optional argument with a default value, and an optional argument with custom prompt suggestions, all configured using the `Arg` function. This setup allows Hexagon to automatically generate interactive prompts and validate user input based on type hints.

```Python
from hexagon.support.input.args import ToolArgs, PositionalArg, OptionalArg, Arg

class Args(ToolArgs):
    # Required positional argument
    name: PositionalArg[str] = Arg(
        None, prompt_message="Enter your name"
    )
    
    # Optional argument with default value
    age: OptionalArg[int] = Arg(
        30, prompt_message="Enter your age"
    )
    
    # Optional argument with custom prompt suggestions
    country: OptionalArg[str] = Arg(
        "USA", 
        prompt_message="Select your country",
        prompt_suggestions=["USA", "Canada", "Mexico", "Other"]
    )
```

--------------------------------

### Storing and Retrieving User Preferences in Python

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/support/storage.md

This example provides utility functions `set_preference` and `get_preference` for managing user preferences. It demonstrates using namespaced keys (e.g., `preference.my_setting`) and handling missing data with a default value when retrieving preferences.

```python
from hexagon.support.storage import store_user_data, get_user_data

def set_preference(key, value):
    """Set a user preference."""
    store_user_data(f"preference.{key}", value)
    return [f"Preference '{key}' set to '{value}'"]

def get_preference(key):
    """Get a user preference."""
    value = get_user_data(f"preference.{key}", default="Not set")
    return [f"Preference '{key}' is '{value}'"]
```

--------------------------------

### Loading Output Themes in Hexagon Printer Module - Python

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/support/output.md

This example illustrates how to load a specific output theme using the `log.load_theme()` method provided by the Hexagon printer module. It shows how to switch the visual style of the console output, mentioning available themes such as 'default', 'disabled', and 'result_only'. This allows customization of the application's console appearance.

```Python
from hexagon.support.output.printer import log

# Load a theme
log.load_theme("default")

# Available themes: default, disabled, result_only
```

--------------------------------

### Example Spanish PO File Content (Gettext PO)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/advanced/internationalization.md

This snippet shows the content of a `.po` file for Spanish translations. It includes metadata about the project and translator, and defines `msgid` (original string) and `msgstr` (translated string) pairs for 'Hello, World!' and 'Goodbye!'. This file is manually edited by translators.

```Gettext PO
# locales/es/LC_MESSAGES/hexagon.po
msgid ""
msgstr ""
"Project-Id-Version: hexagon\n"
"POT-Creation-Date: 2023-01-01 12:00+0000\n"
"PO-Revision-Date: 2023-01-01 12:00+0000\n"
"Last-Translator: Your Name <your.email@example.com>\n"
"Language-Team: Spanish\n"
"Language: es\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

msgid "Hello, World!"
msgstr "¡Hola, Mundo!"

msgid "Goodbye!"
msgstr "¡Adiós!"
```

--------------------------------

### Dynamic Internationalized Greeting with Hexagon Printer Module - Python

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/support/output.md

This example demonstrates internationalization within a `greet` function, combining the `_` function for translation marking with Python's string formatting. It shows how to create a translatable greeting message that can include dynamic content (like a name) and then log this formatted message using `log.info`. The function returns the final internationalized message.

```Python
from hexagon.support.output.printer import _, log

def greet(name):
    greeting = _("Hello, {name}!")
    message = greeting.format(name=name)
    log.info(message)
    return [message]
```

--------------------------------

### Applying Disabled Theme Example (Bash)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/guides/theming.md

This command sets the HEXAGON_THEME environment variable to 'disabled' before running 'mycli'. This theme removes all colors and decorations, providing a plain text interface suitable for environments without ANSI color support.

```bash
HEXAGON_THEME=disabled mycli
```

--------------------------------

### Providing Dynamic Choices and Suggestions for Prompts in Hexagon (Python)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/advanced/prompting.md

This example illustrates how to provide dynamic choices for selection prompts and dynamic suggestions for text input prompts in Hexagon. By passing a function to choices or prompt_suggestions, the options are generated at runtime, ensuring they are always up-to-date.

```python
def get_available_projects():
    # This could fetch data from an API or local storage
    return ["Project A", "Project B", "Project C"]

class Args(ToolArgs):
    # For selection prompts, use choices
    project_select: PositionalArg[str] = Arg(
        None,
        prompt_message="Select a project",
        choices=get_available_projects
    )
    
    # For text input with autocomplete, use prompt_suggestions
    project_name: PositionalArg[str] = Arg(
        None,
        prompt_message="Enter a project name",
        prompt_suggestions=get_available_projects
    )
```

--------------------------------

### Implementing Custom Tool Arguments and Prompting in Hexagon (Python)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/advanced/prompting.md

This example illustrates how to define ToolArgs for a custom Hexagon tool, including PositionalArg and OptionalArg. It demonstrates how to conditionally prompt for argument values if they were not provided via command-line arguments and then access their resolved values within the main function.

```python
from hexagon.support.output.printer import log
from hexagon.support.input.args import ToolArgs, PositionalArg, OptionalArg, Arg

class Args(ToolArgs):
    name: PositionalArg[str] = Arg(
        None, prompt_message="Enter your name"
    )
    age: OptionalArg[int] = Arg(
        30, prompt_message="Enter your age"
    )

def main(tool, env, env_args, cli_args):
    # Only prompt if values weren't provided as command-line arguments
    if not cli_args.name.value:
        cli_args.name.prompt()
    
    if not cli_args.age.value:
        cli_args.age.prompt()
    
    # Access the values directly from cli_args
    log.info(f"Name: {cli_args.name.value}")
    log.info(f"Age: {cli_args.age.value}")
    
    # Return results
    return [
        f"Name: {cli_args.name.value}",
        f"Age: {cli_args.age.value}"
    ]
```

--------------------------------

### Tracking Tool Usage with Hexagon Hooks in Python

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/support/storage.md

This example demonstrates tracking tool usage by integrating with Hexagon's `HexagonHooks.end` event. It retrieves, updates, and stores a JSON object representing tool usage counts, showcasing how to persist dynamic, aggregated data across invocations.

```python
from hexagon.support.storage import store_user_data, get_user_data
from hexagon.support.hooks import HexagonHooks
import json
import time

def setup(cli, tools, envs):
    HexagonHooks.end.register(track_usage)

def track_usage(cli, tools, envs, selected_tool=None):
    if not selected_tool:
        return
    
    # Get existing usage data
    usage_json = get_user_data("tool_usage", default="{}")
    usage = json.loads(usage_json)
    
    # Update usage data
    tool_name = selected_tool.name
    if tool_name not in usage:
        usage[tool_name] = 0
    usage[tool_name] += 1
    
    # Store updated usage data
    store_user_data("tool_usage", json.dumps(usage))
```

--------------------------------

### Registering Hexagon Lifecycle Hooks in a Plugin

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/guides/plugins.md

This snippet illustrates how a Hexagon plugin can register functions to be executed at specific points in Hexagon's lifecycle using `HexagonHooks`. It shows registering `my_start_function` for the `start` hook and `my_end_function` for the `end` hook, demonstrating how to integrate custom logic into Hexagon's execution flow.

```python
from hexagon.support.hooks import HexagonHooks

def setup(cli, tools, envs):
    # Register a hook to run at the start of Hexagon
    HexagonHooks.start.register(my_start_function)
    
    # Register a hook to run at the end of Hexagon
    HexagonHooks.end.register(my_end_function)

def my_start_function():
    print("Hexagon is starting...")

def my_end_function():
    print("Hexagon is ending...")
```

--------------------------------

### Building Static Content with Yarn

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/README.md

This command compiles the website into static HTML, CSS, and JavaScript files, placing them in the `build` directory. The generated content is ready for deployment on any static hosting service.

```Shell
$ yarn build
```

--------------------------------

### Configuring a Web Tool in Hexagon CLI (YAML)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/guides/creating-a-cli.md

This YAML snippet demonstrates how to define a 'web' type tool in Hexagon, which opens a URL. It specifies the tool's name, alias, long name, description, type, environment-specific URLs, and the 'open_link' action. This allows users to quickly access documentation or web resources via the CLI.

```yaml
- name: docs
  alias: d
  long_name: Documentation
  description: Open team documentation
  type: web
  envs:
    development: https://docs-dev.example.com
    staging: https://docs-staging.example.com
    production: https://docs.example.com
  action: open_link
```

--------------------------------

### Programmatically Creating a Cli Instance in Python

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/cli.md

This Python snippet demonstrates how to programmatically create an instance of the `Cli` class. It first instantiates an `EntrypointConfig` object with specific shell, pre-command, and environment settings, then uses it to initialize the `Cli` object with its name, command, custom tools directory, and plugins.

```python
from hexagon.domain.cli import Cli, EntrypointConfig

entrypoint = EntrypointConfig(
    shell="/bin/bash",
    pre_command="source .env",
    environ={"DEBUG": "true"}
)

cli = Cli(
    name="Team CLI",
    command="team",
    entrypoint=entrypoint,
    custom_tools_dir="./custom_tools",
    plugins=["my_plugin"]
)
```

--------------------------------

### Copying Documentation for Translation (Bash)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/tutorial-extras/translate-your-site.md

This bash command sequence creates the necessary directory structure for the French locale's documentation and then copies the original 'intro.md' file into it. This prepares the file for translation into French.

```Bash
mkdir -p i18n/fr/docusaurus-plugin-content-docs/current/

cp docs/intro.md i18n/fr/docusaurus-plugin-content-docs/current/intro.md
```

--------------------------------

### Configuring Web Tool with Environment-Specific URLs (YAML)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/guides/environments.md

This YAML configuration shows how to define a `web` type tool named `docs` that opens different URLs based on the active environment. The `envs` property maps environment names (development, staging, production) to their respective link destinations, ensuring the correct documentation link is opened for each context.

```yaml
- name: docs
  alias: d
  long_name: Documentation
  description: Open team documentation
  type: web
  envs:
    development: https://docs-dev.example.com
    staging: https://docs-staging.example.com
    production: https://docs.example.com
  action: open_link
```

--------------------------------

### Deploying Website via SSH with Yarn

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/README.md

This command deploys the website using SSH for authentication. It's typically used for pushing the built static content to a remote hosting service, such as GitHub Pages, when SSH keys are configured.

```Shell
$ USE_SSH=true yarn deploy
```

--------------------------------

### Defining a Custom Tool with Arguments in Python

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/advanced/custom-tools.md

This Python function `greet` demonstrates how a custom tool can accept arguments. The `name` parameter will automatically receive the value passed from the command line when the tool is invoked. The function returns a personalized greeting as a list of strings.

```python
def greet(name):
    """Greet a person by name."""
    return [f"Hello, {name}!"]
```

--------------------------------

### Configuring a Basic Hexagon Tool in YAML

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/advanced/custom-tools.md

This YAML configuration demonstrates how to register a custom Python tool, `greeting_tool`, as a shell tool named 'greet' in the Hexagon CLI. It includes defining an alias, a long name, a description, and specifying the tool's type and action.

```YAML
- name: greet
  alias: g
  long_name: Greeting
  description: Greet a person
  type: shell
  action: greeting_tool
```

--------------------------------

### Registering Functions with Hexagon Hooks - Python

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/support/hooks.md

This snippet demonstrates how to register functions with the `start` and `end` hooks of the Hexagon CLI using the `HexagonHooks` class. It shows the basic syntax for associating custom functions with specific lifecycle events.

```Python
from hexagon.support.hooks import HexagonHooks

# Register a function with the start hook
HexagonHooks.start.register(my_start_function)

# Register a function with the end hook
HexagonHooks.end.register(my_end_function)
```

--------------------------------

### Configuring Web Tools in Hexagon CLI (YAML)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/guides/tool-types.md

This snippet demonstrates how to configure a web tool in Hexagon CLI. It defines a tool named 'docs' that opens URLs, with different links for 'dev' and 'prod' environments. The type must be 'web' and action must be 'open_link'.

```yaml
- name: docs
  alias: d
  long_name: Documentation
  description: Open team documentation
  type: web
  envs:
    dev: https://docs-dev.example.com
    prod: https://docs.example.com
  action: open_link
```

--------------------------------

### Defining the EntrypointConfig Class in Python

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/cli.md

This Python snippet defines the `EntrypointConfig` class, which configures how a CLI is executed. It includes properties for specifying a custom `shell`, a `pre_command` to run before each tool execution, and `environ` for setting environment variables.

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

--------------------------------

### Storing User Data with store_user_data in Python

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/support/storage.md

This example illustrates how to use the `store_user_data` function to persist a value. It takes a key (string) and a value (any serializable type) and stores it in Hexagon's user-specific storage, typically a JSON file.

```python
from hexagon.support.storage import store_user_data

store_user_data("my_key", "my_value")
```

--------------------------------

### Implementing a Custom Python Tool in Hexagon

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/guides/tool-types.md

This snippet demonstrates the basic structure of a custom Python tool in Hexagon. It defines command-line arguments using the `Args` class and implements the `main` function to access tool configuration, environment details, and handle user input. It uses `log.info` for output and returns a list of strings to be displayed as results.

```python
from hexagon.support.output.printer import log
from hexagon.support.input.args import ToolArgs, PositionalArg, Arg

class Args(ToolArgs):
    name: PositionalArg[str] = Arg(
        None, prompt_message="Enter a name"
    )

def main(tool, env, env_args, cli_args):
    # Access tool configuration
    tool_name = tool.name
    
    # Access environment
    env_name = env.name if env else "No environment"
    
    # Access environment-specific arguments
    env_specific_args = env_args
    
    # Only prompt for command-line arguments if not provided
    if not cli_args.name.value:
        cli_args.name.prompt()
    
    # Output results
    log.info(f"Executing {tool_name} in {env_name}")
    log.info(f"Hello, {cli_args.name.value}!")
    
    # Return results (displayed with log.result())
    return [
        f"Tool: {tool_name}",
        f"Environment: {env_name}",
        f"Environment Args: {env_specific_args}",
        f"Name: {cli_args.name.value}"
    ]
```

--------------------------------

### Retrieving User Data with Default Value in Python

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/support/storage.md

This example shows how to provide a default value to `get_user_data`. If the specified key (`non_existent_key`) is not found in storage, the function will return the provided `default` value instead of `None`, preventing potential errors.

```python
value = get_user_data("non_existent_key", default="default_value")
print(value)  # "default_value"
```

--------------------------------

### Configuring Shell Tool with Environment-Specific Commands (YAML)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/guides/environments.md

This YAML snippet illustrates how to configure a `shell` type tool named `deploy` to execute different shell commands depending on the selected environment. The `envs` property allows specifying distinct commands for development, staging, and production, enabling environment-specific deployment scripts.

```yaml
- name: deploy
  alias: dep
  long_name: Deploy Service
  type: shell
  envs:
    development: "echo 'Deploying to development...' && ./scripts/deploy-dev.sh"
    staging: "echo 'Deploying to staging...' && ./scripts/deploy-staging.sh"
    production: "echo 'Deploying to production...' && ./scripts/deploy-prod.sh"
```

--------------------------------

### Configuring Argument Prompts with Hexagon's Arg Function

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/advanced/prompting.md

This snippet illustrates the various parameters available in Hexagon's `Arg` function, which is used to configure how command-line arguments are prompted and validated. Key parameters include `default` for initial values, `prompt_message` for user guidance, `prompt_suggestions` for autocomplete, and `choices` for selection prompts. These parameters provide fine-grained control over the interactive input experience.

```Python
Arg(
    default,                # Default value for the argument
    *,
    alias=None,             # Alternative name for the argument
    title=None,             # Title displayed in help text
    description=None,       # Description displayed in help text
    prompt_default=None,    # Default value shown in the prompt
    prompt_message=None,    # Message displayed when prompting
    prompt_instruction=None,# Additional instructions for the prompt
    prompt_suggestions=None,# Suggestions for text input autocomplete
    choices=None,           # Options for selection prompts
    searchable=False,       # Whether the prompt supports searching
    # Additional validation parameters
)
```

--------------------------------

### Adding Custom Validation to Arguments in Hexagon (Python)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/advanced/prompting.md

This example shows how to implement custom validation for arguments in Hexagon using Pydantic's @validator decorator. It defines a validator for an email field, ensuring that the input string contains an '@' symbol, and raises a ValueError if validation fails.

```python
from pydantic import validator

class Args(ToolArgs):
    email: PositionalArg[str] = Arg(
        None, prompt_message="Enter your email"
    )
    
    @validator("email")
    def validate_email(cls, v):
        if "@" not in v:
            raise ValueError("Invalid email address")
        return v
```

--------------------------------

### Deploying Website without SSH (GitHub Pages) with Yarn

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/README.md

This command facilitates deployment to GitHub Pages without requiring SSH, instead using a provided GitHub username for authentication. It automates the process of building the website and pushing it to the `gh-pages` branch.

```Shell
$ GIT_USER=<Your GitHub username> yarn deploy
```

--------------------------------

### Configuring a Basic Web Action in YAML

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/actions/web.md

This snippet demonstrates how to configure a web action using the `ActionTool` class. It sets the `type` to `web` and `action` to `open_link`, defining environment-specific URLs for development and production.

```YAML
- name: docs
  alias: d
  long_name: Documentation
  description: Open team documentation
  type: web
  action: open_link
  envs:
    dev: https://docs-dev.example.com
    prod: https://docs.example.com
```

--------------------------------

### Building Docusaurus Site for All Locales (Bash)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/tutorial-extras/translate-your-site.md

This command builds the Docusaurus site, generating static assets for all configured locales. This is the typical command used for production deployments to ensure all language versions are available.

```Bash
npm run build
```

--------------------------------

### Creating Docusaurus Docs Version (Bash)

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/tutorial-extras/manage-docs-versions.md

This Bash command initiates the creation of a new documentation version in Docusaurus. It copies the current `docs` directory content to a version-specific folder (e.g., `versioned_docs/version-1.0`) and updates the `versions.json` file, enabling the management of multiple documentation releases.

```bash
npm run docusaurus docs:version 1.0
```

--------------------------------

### Configuring Environment-Specific Tool Actions in Python

Source: https://github.com/lt-mayonesa/hexagon/blob/main/website/docs/api/env.md

This snippet demonstrates how to define an `ActionTool` with environment-specific configurations. It imports `ActionTool` and `ToolType` and creates a `web_tool` that opens documentation links. The `envs` dictionary maps environment names to different URLs, allowing the tool's behavior to adapt based on the active environment selected in the Hexagon CLI.

```python
from hexagon.domain.tool import ActionTool, ToolType

web_tool = ActionTool(
    name="docs",
    alias="d",
    long_name="Documentation",
    description="Open team documentation",
    type=ToolType.web,
    action="open_link",
    envs={
        "development": "https://docs-dev.example.com",
        "staging": "https://docs-staging.example.com",
        "production": "https://docs.example.com"
    }
)
```