### Install Silverback from Source

Source: https://docs.apeworx.io/silverback/stable/userguides/quickstart

Installs the most up-to-date version of Silverback by cloning the repository and using setuptools. This method is recommended for accessing the latest features.

```shell
git clone https://github.com/ApeWorX/silverback.git silverback
cd silverback
python3 setup.py install
```

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

### Install Silverback via pip

Source: https://docs.apeworx.io/silverback/stable/userguides/quickstart

Installs the latest release of the Silverback library using the pip package installer. Ensure you have Python 3.10 or greater installed.

```shell
pip install silverback
```

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

### Run Silverback Docker Image

Source: https://docs.apeworx.io/silverback/stable/userguides/quickstart

Command to run a Silverback bot using a pre-built Docker image. This allows for consistent execution across different environments. The example uses the `apeworx/silverback-example` image and specifies the network.

```docker
$ docker run -it apeworx/silverback-example:latest run --network :mainnet
```

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

### Run Silverback Bot on Live Network

Source: https://docs.apeworx.io/silverback/stable/userguides/quickstart

Command to execute a Silverback bot against a specified live network. It requires the network configuration and provider to be set correctly. Ensure your environment is configured for the necessary tokens.

```shell
$ silverback run example --network :mainnet:alchemy
```

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

### Install Silverback

Source: https://docs.apeworx.io/silverback/stable/userguides/development

Installs the Silverback Python package using pip. This command is a prerequisite for developing bots with Silverback and ensures you have the necessary libraries.

```bash
pip install silverback
```

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

### Auto-generate Dockerfiles for Bots

Source: https://docs.apeworx.io/silverback/stable/userguides/quickstart

Command to automatically generate Dockerfiles for bots located in the project's `bots/` directory. These Dockerfiles are placed in a `.silverback-images/` directory and are intended for deployment in cloud environments. Note that each bot file is copied individually, and supporting Python functionality is not included.

```shell
silverback build --generate
```

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

### Deploy, Manage, and Remove Bots

Source: https://docs.apeworx.io/silverback/stable/userguides/deploying

Commands for deploying new bots, starting, stopping, updating configurations, and removing bots from the cluster. These operations manage the lifecycle and configuration of your deployed bots.

```shell
silverback cluster bots new <bot-name> --image <container-image> --network <network-name> [--account-alias <alias>] [--env-variable-groups <group1>,<group2>]
# Deploys a new bot with specified name, container image, network, and optional account alias and environment variable groups.
```

```shell
silverback cluster bots start <bot-name>
# Restarts a previously stopped bot.
```

```shell
silverback cluster bots info <bot-name>
# Displays the current configuration and status of a specific bot.
```

```shell
silverback cluster bots update <bot-name> [--metadata <key=value>] [--config <key=value>]
# Updates metadata or runtime configuration parameters for a bot. Note: Configuration changes require a manual restart for them to take effect.
```

```shell
silverback cluster bots remove <bot-name>
# Shuts down and deletes a bot from the cluster. This action will immediately trigger a shutdown if the bot is running.
```

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

### Push Docker Image to Registry

Source: https://docs.apeworx.io/silverback/stable/userguides/deploying

Once your bot container image is built, you can push it to your container registry. This command example shows how to push an image named `botA` with the tag `latest` to a specified registry URL.

```bash
docker push your-registry-url/project/botA:latest
```

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

### BaseRunner Class and Methods

Source: https://docs.apeworx.io/silverback/stable/methoddocs/runner

Defines the abstract base class for Silverback runners. It includes methods for starting up, running the main loop, and shutting down the runner, along with error handling for startup failures and task availability.

```APIDOC
silverback.runner.BaseRunner
  Bases: ABC

  __init__(bot: SilverbackBot, *args, max_exceptions: int = 3, recorder: BaseRecorder | None = None, **kwargs)
    Initializes the BaseRunner with a SilverbackBot instance, optional arguments, maximum exceptions before shutdown, and an optional recorder.

  async run()
    Run the task broker client for the assembled SilverbackBot bot.
    Will listen for events against the connected provider (using ManagerAccessMixin context), and process them by kicking events over to the configured broker.
    Raises:
      StartupFailure: If there was an exception during startup.
      NoTasksAvailableError: If there are no configured tasks to execute.

  async shutdown()
    Execute the runner shutdown sequence, including user tasks.
    NOTE: Must be placed into runtime before called.

  async startup() -> list[Coroutine]
    Execute runner startup sequence to configure the runner for runtime.
    NOTE: Execution will abort if startup sequence has a failure.
    Returns:
      functions to execute as user daemon tasks
    Return type:
      user_tasks (list[Coroutine])
```

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

### Silverback Cluster Bot Control Commands

Source: https://docs.apeworx.io/silverback/stable/userguides/deploying

Commands to manage the lifecycle of bots within a Silverback cluster. These commands are part of the `silverback cluster bots` subcommand group, allowing users to start or stop bots as needed. Control can also be performed via the Platform UI.

```APIDOC
silverback cluster bots start <bot_name>
  - Attempts to start a specified bot.
  - Parameters:
    - bot_name: The name of the bot to start (string).
  - Example:
    silverback cluster bots start my_worker_bot

silverback cluster bots stop <bot_name>
  - Stops a specified bot that is currently in the RUNNING state.
  - Parameters:
    - bot_name: The name of the bot to stop (string).
  - Example:
    silverback cluster bots stop my_worker_bot

Note: Bot control can also be performed via the Platform UI at https://silverback.apeworx.io, provided the user has the necessary permissions.
```

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

### Worker Startup and Shutdown Events

Source: https://docs.apeworx.io/silverback/stable/userguides/development

Define functions that run when a worker process starts or shuts down. These are useful for initializing resources like database connections or performing cleanup. The `state` parameter passed to these functions can be used to store and share data within that specific worker process.

```python
from taskiq import Context, TaskiqDepends
from typing import Annotated

# Assuming 'bot' is an instance of your bot framework

@bot.on_worker_startup()
def handle_on_worker_startup(state):
    # Connect to DB, set initial state, etc.
    # This function runs on every worker process.
    print("Worker starting up...")
    state.db_connection = "established"

@bot.on_worker_shutdown()
def handle_on_worker_shutdown(state):
    # Cleanup resources, close connections cleanly, etc.
    # This function runs on every worker process.
    print("Worker shutting down...")
    if hasattr(state, 'db_connection'):
        print(f"DB connection state: {state.db_connection}")

```

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

### Bot Startup and Shutdown Events

Source: https://docs.apeworx.io/silverback/stable/userguides/development

Define functions that run once when the entire bot application starts or shuts down. These are distinct from worker events and are useful for global initialization or finalization tasks, such as processing historical data or recording final states.

```python
# Assuming 'bot' is an instance of your bot framework

@bot.on_startup()
def handle_on_startup(startup_state):
    # Process missed events, etc.
    # startup_state might contain information like last_block_seen or last_block_processed
    print(f"Bot starting up. Last processed block: {startup_state.last_block_processed}")
    # Example: process_history(start_block=startup_state.last_block_seen)

@bot.on_shutdown()
def handle_on_shutdown():
    # Record final state, etc.
    print("Bot shutting down.")

```

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

### Silverback CLI for Local Development

Source: https://docs.apeworx.io/silverback/stable/commands/run

Provides essential CLI commands for local development of Silverback bots and task workers. This section details commands for initiating bot processes and worker instances, crucial for testing and development workflows.

```bash
silverback run
  Description: Starts the Silverback bot process for local development.
  Usage: silverback run [options]
  Options:
    --config <path>  Specify a custom configuration file path.
    --debug          Enable debug logging.

silverback worker
  Description: Starts a Silverback task worker for processing jobs locally.
  Usage: silverback worker [options]
  Options:
    --queue <name>   Specify the queue name to listen to.
    --concurrency <n> Set the number of worker threads.
    --debug          Enable debug logging.
```

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

### Initialize SilverbackBot Instance

Source: https://docs.apeworx.io/silverback/stable/userguides/development

Shows the basic Python code required to create an instance of the SilverbackBot class. This instance manages state, configuration, and event handling for your bot.

```python
from silverback import SilverbackBot

bot = SilverbackBot()

```

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

### silverback.settings.Settings Class

Source: https://docs.apeworx.io/silverback/stable/methoddocs/settings

Documentation for the `silverback.settings.Settings` class, which manages configuration settings for Silverback bots, including broker, RPC, and signer configurations. It inherits from `BaseSettings` and `ManagerAccessMixin` and provides defaults for various bot parameters.

```APIDOC
silverback.settings.Settings
  Bases: BaseSettings, ManagerAccessMixin

  Settings for the Silverback bot.

  Can override these settings from a default state, typically for advanced testing or deployment purposes. Defaults to a working in-memory broker.

  Parameters:
    *_case_sensitive: bool | None = None
    *_nested_model_default_partial_update: bool | None = None
    *_env_prefix: str | None = None
    *_env_file: DotenvType | None = PosixPath('.')
    *_env_file_encoding: str | None = None
    *_env_ignore_empty: bool | None = None
    *_env_nested_delimiter: str | None = None
    *_env_nested_max_split: int | None = None
    *_env_parse_none_str: str | None = None
    *_env_parse_enums: bool | None = None
    *_cli_prog_name: str | None = None
    *_cli_parse_args: bool | list[str] | tuple[str, ...] | None = None
    *_cli_settings_source: CliSettingsSource[Any] | None = None
    *_cli_parse_none_str: str | None = None
    *_cli_hide_none_type: bool | None = None
    *_cli_avoid_json: bool | None = None
    *_cli_enforce_required: bool | None = None
    *_cli_use_class_docs_for_groups: bool | None = None
    *_cli_exit_on_error: bool | None = None
    *_cli_prefix: str | None = None
    *_cli_flag_prefix_char: str | None = None
    *_cli_implicit_flags: bool | None = None
    *_cli_ignore_unknown_args: bool | None = None
    *_cli_kebab_case: bool | None = None
    *_cli_shortcuts: Mapping[str, str | list[str]] | None = None
    *_secrets_dir: PathType | None = None
    BOT_NAME: str = 'bot'
    FORK_MODE: bool = False
    BROKER_CLASS: str = 'taskiq:InMemoryBroker'
    BROKER_URI: str = ''
    BROKER_KWARGS: dict[str, Any] = {}
    ENABLE_METRICS: bool = False
    RESULT_BACKEND_CLASS: str = 'taskiq.brokers.inmemory_broker:InmemoryResultBackend'
    RESULT_BACKEND_URI: str = ''
    RESULT_BACKEND_KWARGS: dict[str, Any] = {}
    NETWORK_CHOICE: str = ''
    SIGNER_ALIAS: str = ''
    NEW_BLOCK_TIMEOUT: int | None = None
    RECORDER_CLASS: str | None = None
```

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

### Manage Silverback Cluster Bots

Source: https://docs.apeworx.io/silverback/stable/commands/cluster

Provides commands to manage individual BOTs within a Silverback CLUSTER. This includes removing, checking health, starting, stopping, viewing logs, and errors for specified BOTs. Options allow targeting specific clusters and authentication profiles.

```APIDOC
silverback cluster bots remove [OPTIONS] BOT
  Removes one or more BOT(s) from CLUSTER (Shutdown if running).
  Options:
    -c, --cluster <WORKSPACE/NAME>  NAME of the cluster in WORKSPACE you wish to access
    -p, --profile <PROFILE>         The authentication profile to use (Advanced)
  Arguments:
    BOT                             Optional argument

silverback cluster bots health [OPTIONS] BOT
  Show current health of one or more BOT(s) in a CLUSTER.
  Options:
    -c, --cluster <WORKSPACE/NAME>  NAME of the cluster in WORKSPACE you wish to access
    -p, --profile <PROFILE>         The authentication profile to use (Advanced)
  Arguments:
    BOT                             Optional argument

silverback cluster bots start [OPTIONS] BOT
  Start one or more BOT(s) running in CLUSTER (if stopped or terminated).
  Options:
    -c, --cluster <WORKSPACE/NAME>  NAME of the cluster in WORKSPACE you wish to access
    -p, --profile <PROFILE>         The authentication profile to use (Advanced)
  Arguments:
    BOT                             Optional argument

silverback cluster bots stop [OPTIONS] BOT
  Stop one or more BOT(s) from running in CLUSTER (if running).
  Options:
    -c, --cluster <WORKSPACE/NAME>  NAME of the cluster in WORKSPACE you wish to access
    -p, --profile <PROFILE>         The authentication profile to use (Advanced)
  Arguments:
    BOT                             Optional argument

silverback cluster bots logs [OPTIONS] BOT
  Show runtime logs for BOT in CLUSTER.
  Options:
    -l, --log-level <log_level>     Minimum log level to display.
    -s, --since <since>             Return logs since N ago.
    -f, --follow                    Stream logs as they come in
    -c, --cluster <WORKSPACE/NAME>  NAME of the cluster in WORKSPACE you wish to access
    -p, --profile <PROFILE>         The authentication profile to use (Advanced)
  Arguments:
    BOT                             Required argument

silverback cluster bots errors [OPTIONS] BOT
  Show unacknowledged errors for one or more BOT(s) in CLUSTER.
  Options:
    -c, --cluster <WORKSPACE/NAME>  NAME of the cluster in WORKSPACE you wish to access
    -p, --profile <PROFILE>         The authentication profile to use (Advanced)
  Arguments:
    BOT                             Optional argument
```

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

### Silverback CLI Bot Execution Commands

Source: https://docs.apeworx.io/silverback/stable/userguides/development

Demonstrates various ways to run Silverback bots using the CLI, specifying bot names, paths, and network configurations. These commands are essential for deploying and testing bots.

```APIDOC
silverback run --network your:network:of:choice
  - Runs the default bot module in the project root.

silverback run example --network your:network:of:choice
  - Runs a bot module named 'example.py' in the project root.

silverback run example:my_bot --network your:network:of:choice
  - Runs a bot module named 'example.py' where the SilverbackBot instance is named 'my_bot'.

silverback run folder.example:bot --network your:network:of:choice
  - Runs a bot located in 'folder/example.py' with the bot instance named 'bot'.

silverback run --network your:network:of:choice
  - Runs a bot configured via a 'bot/__init__.py' file.
```

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

### Silverback Run Command Options

Source: https://docs.apeworx.io/silverback/stable/commands/run

Details the primary command-line options for the silverback-run command, including account specification, custom runner and recorder configurations, and exception handling.

```APIDOC
--account <account>
  Description: Specifies the account to be used for the operation.
  Type: string
  Usage: --account <account_name>

--runner <CLASS_REF>
  Description: Specifies a custom runner class. The format is '<module>:<CustomRunner>'.
  Type: string
  Dependencies: Requires a valid Python module and class path.
  Usage: --runner my_module:MyCustomRunner

--recorder <CLASS_REF>
  Description: Specifies a custom recorder class. The format is '<module>:<CustomRecorder>'.
  Type: string
  Dependencies: Requires a valid Python module and class path.
  Usage: --recorder another_module:MyCustomRecorder

-x, --max-exceptions <max_exceptions>
  Description: Sets the maximum number of exceptions allowed before execution stops.
  Type: integer
  Constraints: Must be a non-negative integer.
  Usage: -x 5 or --max-exceptions 10

--debug
  Description: Enables debug mode for verbose logging and detailed output.
  Type: flag
  Usage: --debug

Arguments:
  BOT
    Description: An optional argument, likely representing a bot identifier or configuration.
    Type: string (optional)
    Usage: BOT <bot_id>
```

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

### Generate Dockerfiles with silverback build

Source: https://docs.apeworx.io/silverback/stable/userguides/deploying

The `silverback build` command helps in generating Dockerfiles for your bots. It scans the `bots` directory, auto-generates Dockerfiles for each bot module, and places them under the `.silverback-images/` directory. This command is useful for containerizing your bot applications.

```bash
silverback build --generate
```

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

### Silverback Configuration Classes

Source: https://docs.apeworx.io/silverback/stable/methoddocs/main

Data classes for defining system configuration and task data within the Silverback framework. SystemConfig holds SDK version and task types, while TaskData defines task names and labels.

```APIDOC
class SystemConfig(BaseModel):
    sdk_version: str
    task_types: list[str]

    Represents system configuration, including SDK version and task types.
```

```APIDOC
class TaskData(BaseModel):
    name: str
    labels: dict[str, str]

    Represents data associated with a task, including its name and labels.
```

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

### Silverback Worker CLI Options

Source: https://docs.apeworx.io/silverback/stable/commands/run

Configuration options for the Silverback worker command-line interface.

```APIDOC
--account <account>
  Description: Specifies the account to use for the worker.
  Parameters:
    account: The account identifier (string).

```

```APIDOC
-w, --workers <workers>
  Description: Sets the number of worker processes to run.
  Parameters:
    workers: The desired number of worker processes (integer).

```

```APIDOC
-x, --max-exceptions <max_exceptions>
  Description: Defines the maximum number of exceptions allowed before the worker shuts down.
  Parameters:
    max_exceptions: The maximum exception count (integer).

```

```APIDOC
-s, --shutdown_timeout <shutdown_timeout>
  Description: Specifies the duration to wait for graceful shutdown.
  Parameters:
    shutdown_timeout: The timeout value in seconds (number).

```

```APIDOC
--debug
  Description: Enables verbose debug logging for troubleshooting.
  Parameters: None.

```

```APIDOC
BOT
  Description: An optional argument representing the bot to be managed or deployed.
  Parameters:
    BOT: The bot identifier or configuration (string).

```

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

### Silverback Cluster Client Classes

Source: https://docs.apeworx.io/silverback/stable/methoddocs/cluster

Defines client classes for interacting with Silverback Clusters and the Platform. Includes Bot, ClusterClient, PlatformClient, RegistryCredentials, VariableGroup, and Workspace classes.

```APIDOC
class silverback.cluster.client.Bot(*, id: UUID, name: str, created: datetime, image: str, credential_name: str | None, ecosystem: str, network: str, provider: str, account: str | None, environment: list[str])
    Bases: silverback.cluster.types.BotInfo

class silverback.cluster.client.ClusterClient(*args, **kwargs)
    Bases: Client

    send(request, *args, **kwargs)
        Send a request.

        The request is sent as-is, unmodified.

        Typically you’ll want to build one with Client.build_request()
        so that any client-level configuration is merged into the request,
        but passing an explicit httpx.Request() is supported as well.

        See also: Request instances

class silverback.cluster.client.PlatformClient(*args, **kwargs)
    Bases: Client

    send(request, *args, **kwargs)
        Send a request.

        The request is sent as-is, unmodified.

        Typically you’ll want to build one with Client.build_request()
        so that any client-level configuration is merged into the request,
        but passing an explicit httpx.Request() is supported as well.

        See also: Request instances

class silverback.cluster.client.RegistryCredentials(*, id: str, name: str, hostname: str, created: datetime, updated: datetime)
    Bases: silverback.cluster.types.RegistryCredentialsInfo

class silverback.cluster.client.VariableGroup(*, id: UUID, name: str, variables: list[str], created: datetime)
    Bases: silverback.cluster.types.VariableGroupInfo

class silverback.cluster.client.Workspace(*, id: UUID, owner_id: UUID, name: str, slug: str, created: datetime)
    Bases: silverback.cluster.types.WorkspaceInfo
```

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

### SilverbackBot API: Event Handling and Task Decorators

Source: https://docs.apeworx.io/silverback/stable/methoddocs/main

This section details methods for creating event handlers and tasks within the SilverbackBot. It covers listening to containers, applying cron schedules, and dynamically creating broker tasks with specific configurations.

```APIDOC
class SilverbackBot:
    """The bot singleton. Must be initialized prior to use."""

    def on_(container: BlockContainer | ContractEvent, new_block_timeout: int | None = None, start_block: int | None = None, filter_args: dict[str, Any] | None = None, **filter_kwargs: dict[str, Any]) -> Callable:
        """Create task to handle events created by the container trigger.

        Parameters:
        * container – (BlockContainer | ContractEvent): The event source to watch.
        * new_block_timeout – (int | None): Override for block timeout that is acceptable. Defaults to whatever the bot’s settings are for default polling timeout are.
        * start_block (int | None) – block number to start processing events from. Defaults to whatever the latest block is.
        * filter_args: Dictionary of arguments to filter events by.
        * **filter_kwargs: Additional keyword arguments for filtering.

        Returns:
        A function wrapper that will register the task handler.

        Raises:
        * InvalidContainerTypeError – If the type of container is not configurable for the bot.
        """
        pass

    def cron(cron_schedule: str) -> Callable:
        """Create task to run on a schedule.

        Parameters:
        * cron_schedule (str) – A cron-like schedule string.

        Returns:
        A function wrapper that will register the task handler.
        """
        pass

    def broker_task_decorator(task_type: TaskType, container: BlockContainer | ContractEvent | ContractEventWrapper | None = None, filter_args: dict[str, Any] | None = None, cron_schedule: str | None = None, metric_name: str | None = None, value_threshold: dict[str, bool | Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=-39614081257132168796771975168), Le(le=39614081257132168796771975167)])] | float | Decimal] | None = None) → Callable[[Callable], AsyncTaskiqDecoratedTask]:
        """Dynamically create a new broker task that handles tasks of `task_type`.

        Warning:
        Dynamically creating a task does not ensure that the runner will be aware of the task
        in order to trigger it. Use at your own risk.

        Parameters:
        * task_type: The type of task to create.
        * container: The event source to watch.
        * filter_args: Arguments to filter tasks by.
        * cron_schedule: A cron-like schedule string for scheduled tasks.
        * metric_name: Name for metrics associated with the task.
        * value_threshold: Threshold for task execution based on a value.

        Returns:
        A function wrapper that will register the task handler.

        Raises:
        * ContainerTypeMismatchError – If there is a mismatch between task_type and the container type.
        * ContainerConfigurationError – If there is an issue with the arguments provided.
        """
        pass

```

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

### Manage Silverback Cluster Environment Variables

Source: https://docs.apeworx.io/silverback/stable/userguides/deploying

Manages environment variables for bots and services using Variable Groups. These groups help segregate variables based on bot needs. Variables are private and cannot be viewed after upload.

```APIDOC
silverback cluster vars new <group-name> [KEY=VALUE ...]
  - Creates a new Variable Group with the specified name and key-value pairs.
  - Parameters:
    - group-name: The name for the new variable group.
    - KEY=VALUE: Environment variables to include in the group.
  - Returns: Confirmation of group creation.

silverback cluster vars list
  - Lists all existing Variable Groups.
  - Returns: A list of variable group names.

silverback cluster vars info <group-name>
  - Displays information about a specific Variable Group, including its environment variables.
  - Parameters:
    - group-name: The name of the variable group to inspect.
  - Returns: Details of the specified variable group.

silverback cluster vars remove <group-name>
  - Removes a Variable Group. Can only be removed if not referenced by any existing Bot.
  - Parameters:
    - group-name: The name of the variable group to remove.
  - Returns: Confirmation of removal or an error if the group is in use.
```

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

### Silverback CLI Cluster Management

Source: https://docs.apeworx.io/silverback/stable/userguides/managing

Manage Silverback workspaces and clusters using the CLI. This includes logging in, creating, listing, updating, and deleting workspaces and clusters.

```APIDOC
Silverback CLI Cluster Management:

Login to the Silverback Platform:

silverback login
  - Logs the user into the Silverback Platform.
  - Usage: Execute the command to initiate the login process.

Workspace Management:

silverback cluster workspaces
  - Entry point for managing workspaces.
  - Subcommands:
    - list
      - Lists all available workspaces.
      - Parameters: None
      - Returns: List of workspaces.
    - new
      - Creates a new workspace.
      - Parameters: (e.g., name, description)
      - Returns: Details of the newly created workspace.
    - info <workspace_id>
      - Retrieves configuration information for a specific workspace.
      - Parameters:
        - workspace_id: The unique identifier of the workspace.
      - Returns: Workspace configuration details.
    - update <workspace_id>
      - Updates metadata for a specific workspace.
      - Parameters:
        - workspace_id: The unique identifier of the workspace.
        - (e.g., new_name, new_description)
      - Returns: Updated workspace information.
    - delete <workspace_id>
      - Deletes a specific workspace.
      - Parameters:
        - workspace_id: The unique identifier of the workspace.
      - Returns: Confirmation of deletion.

Cluster Management:

silverback cluster new
  - Creates and deploys a new cluster.
  - Follows steps necessary to deploy a cluster within a workspace.
  - Parameters: (e.g., workspace_id, cluster_name, region)
  - Returns: Details of the newly created cluster.

silverback cluster list
  - Lists all existing clusters.
  - Parameters: (Optional: workspace_id)
  - Returns: List of clusters.

silverback cluster update <cluster_id>
  - Updates an existing cluster.
  - Parameters:
    - cluster_id: The unique identifier of the cluster.
    - (e.g., new_config, new_tags)
  - Returns: Updated cluster information.

Error Conditions:
  - Authentication errors if not logged in.
  - Invalid workspace or cluster IDs.
  - Permissions errors for specific operations.
```

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

### Retry Bot Builds

Source: https://docs.apeworx.io/silverback/stable/userguides/deploying

After generating Dockerfiles, you can use the `silverback build` command again to build the container images. This assumes your project structure remains unchanged. It's a way to re-run the build process for your bot containers.

```bash
silverback build
```

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

### Silverback Cluster Settings Classes

Source: https://docs.apeworx.io/silverback/stable/methoddocs/cluster

Defines configuration classes for managing Silverback profiles and authentication. Includes AuthenticationConfig, BaseProfile, ClusterProfile, PlatformProfile, and ProfileSettings.

```APIDOC
class silverback.cluster.settings.AuthenticationConfig(*, host: str = 'https://account.apeworx.io', client_id: str = 'c9f9be0e-1f0a-474c-b79e-319778b37ae6')
    Bases: BaseModel

    Authentication host configuration information (~/.silverback/profile.toml)

class silverback.cluster.settings.BaseProfile(*, host: str)
    Bases: BaseModel

    Profile information (~/.silverback/profile.toml)

class silverback.cluster.settings.ClusterProfile(*, host: str, api_key: str)
    Bases: silverback.cluster.settings.BaseProfile

class silverback.cluster.settings.PlatformProfile(*, host: str, auth: str, default_workspace: str = '', default_cluster: dict[str, str] = <factory>)
    Bases: silverback.cluster.settings.BaseProfile

class silverback.cluster.settings.ProfileSettings(*, auth: dict[str, AuthenticationConfig], profile: dict[str, PlatformProfile | ClusterProfile], default_profile: str = 'default')
    Bases: BaseModel

    Configuration settings for working with Bot Clusters and the Silverback Platform
```

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

### silverback.types Module API Documentation

Source: https://docs.apeworx.io/silverback/stable/methoddocs/types

Comprehensive API documentation for the silverback.types module. This includes class definitions, method signatures, parameter descriptions, and return types for key data structures like Datapoint, Datapoints, ScalarDatapoint, SilverbackID, and TaskType.

```APIDOC
silverback.types

Module for defining core data types and structures used by the Silverback framework.

Contents:

* [`Datapoint`](#silverback.types.Datapoint)
* [`Datapoints`](#silverback.types.Datapoints)
* [`ScalarDatapoint`](#silverback.types.ScalarDatapoint)
  + [`render()`](#silverback.types.ScalarDatapoint.render)
* [`SilverbackID`](#silverback.types.SilverbackID)
* [`TaskType`](#silverback.types.TaskType)

---

Datapoint

:   alias of [`ScalarDatapoint`](#silverback.types.ScalarDatapoint "silverback.types.ScalarDatapoint")

    A type alias for `ScalarDatapoint`, representing a generic data point.

---

Datapoints

*class* silverback.types.Datapoints(*root: RootModelRootType = PydanticUndefined*)
:   Bases: `RootModel`

    Represents a collection of data points, likely used for batch operations or structured data.
    This class inherits from Pydantic's `RootModel`.

---

ScalarDatapoint

*class* silverback.types.ScalarDatapoint(*\*, *type: Literal['scalar'] = 'scalar'*, *data: bool | Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=-39614081257132168796771975168), Le(le=39614081257132168796771975167)])] | float | Decimal*)
:   Bases: `_BaseDatapoint`

    Represents a scalar data point, which can be a boolean, integer, float, or Decimal.
    It includes a type hint indicating it's specifically a 'scalar' type.

    render() → str
    :   Render Datapoint for viewing in logs

        This method serializes the scalar data point into a string representation suitable for logging.

---

SilverbackID

*class* silverback.types.SilverbackID(*\*, *name: str*, *ecosystem: str*, *network: str*)
:   Bases: `BaseModel`

    Represents a unique identifier within the Silverback ecosystem, composed of name, ecosystem, and network.
    This class inherits from Pydantic's `BaseModel` for data validation.

    Parameters:
      - name (str): The name component of the ID.
      - ecosystem (str): The ecosystem component of the ID.
      - network (str): The network component of the ID.

---

TaskType

*class* silverback.types.TaskType(*value*)
:   Bases: `str`, `Enum`

    An enumeration representing different types of tasks within the Silverback system.
    It inherits from `str` and `Enum`.


```

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

### Run Silverback Bot Command

Source: https://docs.apeworx.io/silverback/stable/commands/run

Executes the Silverback bot. This command allows specifying options to control verbosity and network settings. The optional BOT argument can be used to target a specific bot instance.

```shell
silverback run [OPTIONS] [BOT]

Options:
  -v, --verbosity <LVL>  One of ERROR, WARNING, SUCCESS, INFO, or DEBUG
  --network <network>    Override the default network and provider. (see ape networks list for options)
```

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

### Configure Private Container Registries for Silverback

Source: https://docs.apeworx.io/silverback/stable/userguides/deploying

Manages credentials for accessing private container registries. These credentials are used by bots to pull images from private repositories.

```APIDOC
silverback cluster registry new <registry-name> --username <username> --password <password> --server <server-url>
  - Adds credentials for a private container registry to the cluster.
  - Parameters:
    - registry-name: A name to identify this registry credential set.
    - --username: The username for the private registry.
    - --password: The password for the private registry.
    - --server: The URL of the container registry server.
  - Returns: Confirmation of credential addition.

silverback cluster bots new <bot-name> --image <image-name> --registry <registry-name> [...]
  - Creates a new bot, specifying the private registry credentials to use for image pulling.
  - Parameters:
    - bot-name: The name of the bot to create.
    - --image: The container image name.
    - --registry: The name of the previously added registry credentials.

silverback cluster bots update <bot-name> --image <image-name> --registry <registry-name> [...]
  - Updates an existing bot, allowing specification of private registry credentials for image pulling.
  - Parameters:
    - bot-name: The name of the bot to update.
    - --image: The container image name.
    - --registry: The name of the previously added registry credentials.
```

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

### Monitor Bot Health and Activity

Source: https://docs.apeworx.io/silverback/stable/userguides/deploying

Commands to monitor the status, health, logs, and errors of your deployed bots. These tools help ensure your bots are running correctly and diagnose issues.

```shell
silverback cluster bots list
# Lists all bots managed by the cluster, showing their current state (e.g., RUNNING, STOPPED, PROVISIONING).
```

```shell
silverback cluster bots health <bot-name>
# Retrieves detailed runtime health information for a specific bot.
```

```shell
silverback cluster bots logs <bot-name>
# Displays the logs generated by a specific bot.
```

```shell
silverback cluster bots errors <bot-name>
# Shows unacknowledged errors encountered by a specific bot during task execution while in the RUNNING state.
```

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

### Claude Desktop MCP Configuration

Source: https://docs.apeworx.io/silverback/stable/userguides/managing

Configuration for integrating Silverback's Model Context Protocol (MCP) server with Claude Desktop. This allows LLMs to interact with your Silverback cluster via a local MCP server.

```json
{
  "mcpServers": {
    "silverback": {
      "command": "<path to `uvx` or `uv` binary>",
      "args": [
        "silverback[mcp]",
        "cluster",
        "mcp"
        // Add args `--cluster <cluster name>` to use a Cluster other than your default
      ]
    }
  }
}
```

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

### Silverback Cluster Bots CLI Commands

Source: https://docs.apeworx.io/silverback/stable/commands/cluster

Provides commands to manage bots within Silverback clusters. This includes listing bots, retrieving detailed information about specific bots, and updating bot configurations.

```APIDOC
silverback cluster bots list [OPTIONS]

List all bots in a CLUSTER by network (Regardless of status)

Options:
  -c, --cluster <WORKSPACE/NAME>  NAME of the cluster in WORKSPACE you wish to access
  -p, --profile <PROFILE>         The authentication profile to use (Advanced)
```

```APIDOC
silverback cluster bots info [OPTIONS] BOT

Get configuration information of one or more BOT(s) in a CLUSTER

Options:
  -c, --cluster <WORKSPACE/NAME>  NAME of the cluster in WORKSPACE you wish to access
  -p, --profile <PROFILE>         The authentication profile to use (Advanced)

Arguments:
  BOT                             Optional argument
```

```APIDOC
silverback cluster bots update [OPTIONS] BOT

Update configuration of BOT in CLUSTER
NOTE: Some configuration updates will trigger a redeploy

Options:
  --new-name <new_name>           
  -i, --image <image>             
  -n, --network <network>         
  -a, --account <account>         
  -g, --group <environment>       
  --clear-vars                    
  --credential <credential_name>  registry credentials to use to pull the image
  -c, --cluster <WORKSPACE/NAME>  NAME of the cluster in WORKSPACE you wish to access
  -p, --profile <PROFILE>         The authentication profile to use (Advanced)

Arguments:
  BOT                             Required argument
```

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

### silverback.utils Module Functions

Source: https://docs.apeworx.io/silverback/stable/methoddocs/utils

Documentation for the utility functions within the silverback.utils module. This includes functions for asynchronous operations, data manipulation, and encoding/decoding specific data formats.

```APIDOC
silverback.utils:
  Module for utility functions.

  Functions:
    async_wrap_iter(*it: Iterator) -> AsyncIterator
      Description: Wrap blocking iterator into an asynchronous one.
      Parameters:
        it: The blocking iterator to wrap.
      Returns: An asynchronous iterator.

    clean_hexbytes_dict(data: dict, recurse_count: int = 0) -> dict
      Description: Strips HexBytes objects from dictionary values, as they do not encode well.
      Parameters:
        data: The dictionary to clean.
        recurse_count: Internal counter for recursion depth.
      Returns: A new dictionary with HexBytes values removed.

    decode_topics_from_string(encoded_topics: str) -> list[list[HexStr] | HexStr | None]
      Description: Decode a topic list from a TaskIQ label into Web3py topics.
      Parameters:
        encoded_topics: The string representation of encoded topics.
      Returns: A list representing the decoded topics.

    encode_topics_to_string(topics: list[list[HexStr] | HexStr | None]) -> str
      Description: Encode a topic list to a string, for TaskIQ label.
      Parameters:
        topics: The list of topics to encode.
      Returns: A string representation of the encoded topics.

    parse_hexbytes_dict(data: dict, recurse_count: int = 0) -> dict
      Description: Converts any hex string values in a flat dictionary to HexBytes.
      Parameters:
        data: The dictionary to parse.
        recurse_count: Internal counter for recursion depth.
      Returns: A new dictionary with hex string values converted to HexBytes.
```

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

### Define StartupFailure Exception in Python

Source: https://docs.apeworx.io/silverback/stable/methoddocs/exceptions

Exception raised during the startup phase of the application, indicating a failure to initialize properly. It can wrap multiple underlying exceptions and inherits from SilverbackException and ClickException.

```Python
class StartupFailure(SilverbackException, ClickException):
    """""
```

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

### ClusterConfiguration Data Structure and Methods

Source: https://docs.apeworx.io/silverback/stable/methoddocs/cluster

Represents the configuration settings for a cluster, including resource limits and encoding/decoding methods. It allows defining CPU, memory, network, bot, bandwidth, and duration limits.

```APIDOC
ClusterConfiguration:
  version: int
    Version of this configuration (used for encoding/decoding).
  cpu: Annotated[int, Field(ge=1, le=64)]
    Max vCPUs shared by all bots in cluster.
  memory: Annotated[int, Field(ge=1, le=128)]
    Max memory (in GiB) shared by all bots in cluster.
  networks: Annotated[int, Field(ge=1, le=20)]
    Maximum number of concurrent networks all bots can use.
  bots: Annotated[int, Field(ge=1, le=250)]
    Maximum number of guaranteed concurrently running bots.
  bandwidth: Annotated[int, Field(ge=1, le=250)]
    Rate at which data should be emitted by cluster (in KiB/sec).
  duration: Annotated[int, Field(ge=1, le=120)]
    Time to keep data recording duration (in months).

  classmethod decode(value: Any) -> ClusterConfiguration
    Decode the configuration from 8 byte integer value.

  encode() -> int
    Encode configuration as 8 byte integer value.
```