genai-toolbox/docs/en/reference/cli.md at 0a21809c2abbec934409c76ec744479a092cbc2e

mirror of https://github.com/googleapis/genai-toolbox.git synced 2026-02-04 04:05:22 -05:00

Files

dishaprakash e535b372ea feat: Support combining multiple prebuilt configurations (#2295 )

## Description
This PR introduces support for merging multiple prebuilt configurations.
To ensure compatibility, the following restrictions apply:

- No Naming Collisions: Configurations cannot share duplicate names for
any resources (Tools, Sources, Toolsets, Auth Services, etc.).
- Shared Environment Variables: If multiple sources rely on the same
environment variable, they must share the same value; unique values for
the same variable are not supported

## Usage Examples

### Successful Initialization

You can load multiple prebuilt configurations by either repeating the
--prebuilt flag or by providing a comma-separated list.

**Option 1:** Multiple Flags
```
./toolbox --prebuilt alloydb-postgres --prebuilt alloydb-postgres-admin
```

**Option 2:** Comma-Separated Values
```
./toolbox --prebuilt alloydb-postgres,alloydb-postgres-admin
```

### Initialization Failure (Resource Conflict)

If two or more configurations define a resource with the same name (such
as a Tool or Source, etc.), the server will fail to start and display a
conflict error.

```
./toolbox --prebuilt alloydb-postgres --prebuilt cloud-sql-mysql
2026-01-13T11:14:50.758121799Z INFO "Using prebuilt tool configurations for: alloydb-postgres, cloud-sql-mysql" 
2026-01-13T11:14:50.764578167Z ERROR "resource conflicts detected:\n  - tool 'execute_sql' (file #2)\n  - tool 'list_active_queries' (file #2)\n  - tool 'get_query_plan' (file #2)\n  - tool 'list_tables' (file #2)\n\nPlease ensure each source, authService, tool, toolset and prompt has a unique name across all files" 
```

## PR Checklist

> Thank you for opening a Pull Request! Before submitting your PR, there
are a
> few things you can do to make sure it goes smoothly:

- [x] Make sure you reviewed

[CONTRIBUTING.md](https://github.com/googleapis/genai-toolbox/blob/main/CONTRIBUTING.md)
- [x] Make sure to open an issue as a

[bug/issue](https://github.com/googleapis/genai-toolbox/issues/new/choose)
  before writing your code! That way we can discuss the change, evaluate
  designs, and agree on the general idea
- [x] Ensure the tests and linter pass
- [x] Code coverage does not decrease (if any source code was changed)
- [x] Appropriate docs were updated (if necessary)
- [x] Make sure to add `!` if this involve a breaking change

🛠️ Fixes #1855

---------

Co-authored-by: Averi Kitsch <akitsch@google.com>

2026-01-22 23:00:17 +00:00

6.9 KiB

Raw Blame History

title, type, weight, description

title	type	weight	description
CLI	docs	1	This page describes the `toolbox` command-line options.

Reference

Flag (Short)	Flag (Long)	Description	Default
`-a`	`--address`	Address of the interface the server will listen on.	`127.0.0.1`
	`--disable-reload`	Disables dynamic reloading of tools file.
`-h`	`--help`	help for toolbox
	`--log-level`	Specify the minimum level logged. Allowed: 'DEBUG', 'INFO', 'WARN', 'ERROR'.	`info`
	`--logging-format`	Specify logging format to use. Allowed: 'standard' or 'JSON'.	`standard`
`-p`	`--port`	Port the server will listen on.	`5000`
	`--prebuilt`	Use one or more prebuilt tool configuration by source type. See Prebuilt Tools Reference for allowed values.
	`--stdio`	Listens via MCP STDIO instead of acting as a remote HTTP server.
	`--telemetry-gcp`	Enable exporting directly to Google Cloud Monitoring.
	`--telemetry-otlp`	Enable exporting using OpenTelemetry Protocol (OTLP) to the specified endpoint (e.g. 'http://127.0.0.1:4318')
	`--telemetry-service-name`	Sets the value of the service.name resource attribute for telemetry data.	`toolbox`
	`--tools-file`	File path specifying the tool configuration. Cannot be used with --tools-files or --tools-folder.
	`--tools-files`	Multiple file paths specifying tool configurations. Files will be merged. Cannot be used with --tools-file or --tools-folder.
	`--tools-folder`	Directory path containing YAML tool configuration files. All .yaml and .yml files in the directory will be loaded and merged. Cannot be used with --tools-file or --tools-files.
	`--ui`	Launches the Toolbox UI web server.
	`--allowed-origins`	Specifies a list of origins permitted to access this server for CORs access.	`*`
	`--allowed-hosts`	Specifies a list of hosts permitted to access this server to prevent DNS rebinding attacks.	`*`
	`--user-agent-extra`	Appends additional metadata to the User-Agent.
`-v`	`--version`	version for toolbox

Examples

Transport Configuration

Server Settings:

--address, -a: Server listening address (default: "127.0.0.1")
--port, -p: Server listening port (default: 5000)

STDIO:

--stdio: Run in MCP STDIO mode instead of HTTP server

Usage Examples

# Basic server with custom port configuration
./toolbox --tools-file "tools.yaml" --port 8080

# Server with prebuilt + custom tools configurations
./toolbox --tools-file tools.yaml --prebuilt alloydb-postgres

# Server with multiple prebuilt tools configurations
./toolbox --prebuilt alloydb-postgres,alloydb-postgres-admin
# OR
./toolbox --prebuilt alloydb-postgres --prebuilt alloydb-postgres-admin

Tool Configuration Sources

The CLI supports multiple mutually exclusive ways to specify tool configurations:

Single File: (default)

--tools-file: Path to a single YAML configuration file (default: tools.yaml)

Multiple Files:

--tools-files: Comma-separated list of YAML files to merge

Directory:

--tools-folder: Directory containing YAML files to load and merge

Prebuilt Configurations:

--prebuilt: Use one or more predefined configurations for specific database types (e.g., 'bigquery', 'postgres', 'spanner'). See Prebuilt Tools Reference for allowed values.

{{< notice tip >}} The CLI enforces mutual exclusivity between configuration source flags, preventing simultaneous use of the file-based options ensuring only one of --tools-file, --tools-files, or --tools-folder is used at a time. {{< /notice >}}

Hot Reload

Toolbox enables dynamic reloading by default. To disable, use the --disable-reload flag.

Toolbox UI

To launch Toolbox's interactive UI, use the --ui flag. This allows you to test tools and toolsets with features such as authorized parameters. To learn more, visit Toolbox UI.

6.9 KiB Raw Blame History