Setting Up the CLI

Get the rootcoz command-line tool installed, connected to your server, and authenticated so you can submit analyses, query results, and manage jobs without leaving your terminal.

Prerequisites:

• A running rootcoz server (see Quickstart)
• Python 3.12 or later
• uv package manager (recommended) or pip

Quick example

uv tool install rootcoz
export ROOTCOZ_SERVER=http://localhost:8000
rootcoz health

If you see Status: healthy, you're ready to go.

Installing the CLI

The recommended way to install is with uv tool, which gives you an isolated rootcoz command:

uv tool install rootcoz

Alternatively, install with pip:

pip install rootcoz

Verify the installation:

rootcoz --help

This prints all available commands and global options.

Connecting to a server

The CLI needs to know which rootcoz server to talk to. You have three options, from quickest to most permanent.

Option 1: Environment variable

export ROOTCOZ_SERVER=http://localhost:8000
rootcoz health

Option 2: CLI flag

rootcoz --server http://localhost:8000 health

Option 3: Config file (recommended)

Create ~/.config/rootcoz/config.toml to store server connections permanently:

mkdir -p ~/.config/rootcoz
cat > ~/.config/rootcoz/config.toml << 'EOF'
[default]
server = "dev"

[servers.dev]
url = "http://localhost:8000"
username = "myuser"
EOF

Now every command uses the dev server automatically:

rootcoz health

Tip: The config file location follows the XDG Base Directory Specification. Set XDG_CONFIG_HOME to change the base path.

Verify your config with:

rootcoz config show

Authenticating

Most operations require authentication. Register a user account on the server to get an API key:

rootcoz register myuser

Output:

Registered: myuser

⚠️  Save this API key — you won't see it again!
API Key: rcz_a1b2c3d4e5f6...

Warning: Copy the API key immediately. It is only shown once and cannot be retrieved later.

Storing your API key

Add the key to your config file so you don't have to pass it on every command:

[servers.dev]
url = "http://localhost:8000"
username = "myuser"
api_key = "rcz_a1b2c3d4e5f6..."

Alternatively, use an environment variable or CLI flag:

# Environment variable
export ROOTCOZ_API_KEY=rcz_a1b2c3d4e5f6...

# CLI flag
rootcoz --api-key rcz_a1b2c3d4e5f6... results list

Verifying authentication

rootcoz auth whoami

This shows your username, role, and admin status.

Running your first analysis

Submit a Jenkins job for analysis:

rootcoz analyze --job-name my-pipeline --build-number 42

Output:

Job queued: a1b2c3d4-e5f6-...
Status: queued
Poll: http://localhost:8000/results/a1b2c3d4-e5f6-...

Check the status:

rootcoz status a1b2c3d4-e5f6-...

View the result once it completes:

rootcoz results show a1b2c3d4-e5f6-...

For the full JSON response, add --full:

rootcoz results show a1b2c3d4-e5f6-... --full

Analyzing a JUnit XML file

You can also analyze a local JUnit XML file without Jenkins:

rootcoz analyze --source file --file test-results.xml

For more analysis options, see Analyzing Test Failures.

Global options

Every command supports these flags:

Note: --verify-ssl and --insecure are mutually exclusive.

Config file reference

The config file uses TOML format with three sections:

# Set the default server for all commands
[default]
server = "dev"

# Shared settings inherited by all servers
[defaults]
jenkins_url = "https://jenkins.example.com"
jenkins_user = "ci-bot"
jenkins_password = "api-token"
ai_provider = "claude"
ai_model = "opus-4"
tests_repo_url = "https://github.com/org/tests"

# Per-server configuration
[servers.dev]
url = "http://localhost:8000"
username = "myuser"
api_key = "rcz_..."

[servers.prod]
url = "https://rootcoz.example.com"
username = "prod-user"
no_verify_ssl = false
# Override defaults for this server
ai_provider = "gemini"
ai_model = "gemini-2.5-pro"

The [defaults] section is optional. Any field set there is inherited by every server entry. Per-server values override defaults.

Available config fields

Priority order

Settings are resolved with this priority (highest wins):

1. CLI flags (e.g. --provider claude)
2. Environment variables (e.g. ROOTCOZ_API_KEY)
3. Per-server config (e.g. [servers.dev])
4. Global defaults (e.g. [defaults])
5. Server-side defaults

Switching between servers

Use --server to target a specific server by config name:

rootcoz --server prod results list
rootcoz --server dev analyze --job-name my-job --build-number 1

Or pass a URL directly to skip config resolution:

rootcoz --server https://rootcoz.example.com health

List all configured servers:

rootcoz config servers

Shell completion

Enable tab completion for faster command entry:

# Show setup instructions
rootcoz config completion zsh    # or: bash

Follow the printed instructions to add the completion to your shell config.

Advanced Usage

JSON output for scripting

Every command supports --json for machine-readable output. This makes it easy to pipe into jq or other tools:

rootcoz results list --json | jq '.[].job_id'
rootcoz --json results show a1b2c3d4-... | jq '.result.failures | length'

Rotating your API key

If your key is compromised, rotate it immediately:

rootcoz auth rotate-key

The new key is printed once — update your config file with the replacement.

Self-signed certificates

When connecting to servers with self-signed SSL certificates, disable verification per-server in your config:

[servers.internal]
url = "https://rootcoz.internal.local"
no_verify_ssl = true

Or per-command:

rootcoz --insecure --server https://rootcoz.internal.local health

Warning: Disabling SSL verification reduces security. Only use this for trusted internal servers.

Multiple config profiles

Define separate profiles for different environments, teams, or credentials:

[default]
server = "team-a"

[defaults]
ai_provider = "claude"

[servers.team-a]
url = "https://rootcoz-a.example.com"
username = "alice"
api_key = "rcz_aaa..."
jira_project_key = "TEAMA"

[servers.team-b]
url = "https://rootcoz-b.example.com"
username = "alice"
api_key = "rcz_bbb..."
jira_project_key = "TEAMB"
ai_provider = "gemini"

Troubleshooting

"No server specified" — Set ROOTCOZ_SERVER, use --server, or create a config file. Run rootcoz config show to check your current configuration.

"HTTP 401" / "Use --api-key or set ROOTCOZ_API_KEY" — Your API key is missing or invalid. Register with rootcoz register <username> and save the key to your config file.

"HTTP 403" / "requires a higher role" — Your user role doesn't have permission for this action. Contact an admin to upgrade your role. See Managing Users and Roles for the role hierarchy.

"Cannot connect to ..." — The server is unreachable. Verify the URL is correct and the server is running with rootcoz health.

"Request timed out" — The server took too long to respond. This can happen during large analyses. Increase the timeout or check server health.

SSL errors connecting to Jenkins/Jira — If the target service uses a self-signed certificate, disable verification for that integration:

rootcoz analyze --job-name my-job --build-number 1 --no-jenkins-ssl-verify

Or set it permanently in config:

[servers.dev]
url = "http://localhost:8000"
jenkins_ssl_verify = false
jira_ssl_verify = false

For the full command reference, see CLI Command Reference. For ready-to-use workflow recipes, see CLI Recipes.

Related Pages

• Quickstart
• CLI Command Reference
• CLI Recipes
• Analyzing Test Failures
• Managing Users and Roles