BYOT CLI Reference

CLI Usage

pip

sec-gemini-byot [OPTIONS]

uv (standalone)

uvx --from sec-gemini sec-gemini-byot [OPTIONS]

Flags

Flag	Required	Default	Description
--api-key API_KEY	No	config / env	API key (falls back to SEC_GEMINI_API_KEY env, then config.toml)
--name NAME	No	local	Display name for this BYOT client
--hub HUB	No	production hub	Hub address URL
--list-tools	No	–	List available base tools and exit
--tools TOOL [...]	No	all	Only enable these base tools
--no-base-tools	No	–	Disable all base tools
--mcp PATH [PATH ...]	No	[]	Additional MCPs as file paths (.py) or URLs
--verbose	No	false	Enable DEBUG-level console output

Base Tools

Enabled by default. 35 tools in 5 categories. Use --no-base-tools to disable, or --tools to select specific ones.

Security

These tools run on your local machine with your user privileges and no sandboxing. See Security Considerations for isolation guidance.

File Operations (9 tools)

Tool	Description
read_file	Read the contents of a file at the given path
write_file	Write content to a file (requires prior read_file for the same path)
edit_file	Apply search/replace edits to a file (requires prior read_file)
list_directory	List files and directories at a given path
grep	Search file contents using a regular expression pattern
find_files	Find files matching a glob pattern
file_info	Get file metadata: size, permissions, modification time
remove_file	Delete a single file
remove_directory	Recursively delete a directory

Shell (6 tools)

Tool	Description
bash	Execute a shell command and return stdout/stderr
run_background	Start a long-running process in the background
list_background	List all running background processes
peek_background	View recent output from a background process
stop_background	Terminate a background process
read_background	Read the full captured output of a completed process

Python Execution (4 tools)

Tool	Description
python_exec	Execute Python code in an isolated virtual environment
python_install	Install Python packages via pip into the execution environment
python_packages	List installed Python packages in the execution environment
python_find_packages	Search PyPI for available packages

JavaScript Execution (4 tools)

Tool	Description
javascript_exec	Execute JavaScript code via Node.js
javascript_install	Install npm packages into the execution environment
javascript_packages	List installed npm packages in the execution environment
javascript_find_packages	Search npm for available packages

Network (12 tools)

Tool	Description
dns_lookup	Query DNS records (A, AAAA, MX, NS, TXT, CNAME, SOA)
whois_lookup	Perform a WHOIS query for a domain or IP
tcp_port_check	Check if a TCP port is open on a host
tcp_send	Send raw data over a TCP connection
ping	Send ICMP ping to a host
traceroute	Trace the network path to a host
fetch_http	Fetch the content of an HTTP(S) URL
grep_http	Fetch an HTTP URL and search response body with regex
http_headers	Get HTTP response headers for a URL
fetch_file	Download a file from a URL to a local path
ssl_check	Inspect the SSL/TLS certificate of a host
check_email_security	Check SPF, DKIM, and DMARC records for a domain

File Write Safety

The baseline tools enforce a read-before-write guard:

1. write_file and edit_file require a prior read_file for the same path.
2. If the file content has changed since the last read (detected via sha256), the write is rejected.
3. This prevents the agent from blindly overwriting files it hasn’t inspected.

Connection Lifecycle

State	Description
STOPPED	Client is not running
STARTING	Connecting to the BYOT Hub
RUNNING	Connected and processing tool requests
STOPPING	Shutting down gracefully
ERROR	Connection failed after max retries

Retry behavior: Exponential backoff starting at 4 seconds, capped at 30 seconds, up to 10 attempts.

Log Files

BYOT logs to ~/.config/sec-gemini/logs/byot.log (JSON format, automatic rotation).

Use --verbose for real-time DEBUG output to the console.