CLI Command Reference

rootcoz [GLOBAL OPTIONS] COMMAND [ARGS]...

Note: For profile fields, config file layout, and environment-backed defaults, see Configuration Reference.

Tip: For task-focused command patterns, see Automating Common Tasks with the CLI.

Note: For HTTP request and response schemas, see API Endpoint Reference.

Global Options

These options are accepted before the command name.

Warning: --verify-ssl and --insecure cannot be used together.

Note: When --server is a full URL, profile values do not cascade into the command. When --server is omitted, rootcoz uses the default profile from $XDG_CONFIG_HOME/rootcoz/config.toml or ~/.config/rootcoz/config.toml.

Example:

rootcoz --server dev --json results list

Output Modes

Note: Command tables below list command-specific parameters only. Apply the global options above to any leaf command unless the command section says otherwise.

Example:

rootcoz --json health
rootcoz results list --json
rootcoz results show job-123 --full
rootcoz admin token-usage --group-by provider --format csv

Analysis and Results

Tip: See Submitting Jenkins Builds and JUnit XML, Tracking Analysis Progress, and Finding Runs on the Dashboard for workflow guidance.

health

Checks server availability.

Example:

rootcoz health

Return value/effect: Prints the current service status and any named health checks.

analyze

Queues a Jenkins build for analysis.

Note: Unset options can fall back to the selected server profile. Env-backed flags read the environment variable named in the description before profile fallback.

Warning: --build-number, --ai-cli-timeout, --jenkins-timeout, --jenkins-artifacts-max-size-mb, --jira-max-results, and --poll-interval must be greater than 0 when set. --max-wait and --max-concurrent must be non-negative. --peer-analysis-max-rounds must be between 1 and 10.

Core options

Jenkins and repository options

Jira, GitHub, and peer-AI options

Queue and concurrency options

Example:

rootcoz analyze \
  --job-name ocp-e2e-aws \
  --build-number 1542 \
  --provider claude \
  --model claude-sonnet-4 \
  --wait

Return value/effect: Queues the analysis and prints the new job_id, queue status, and result polling URL.

re-analyze

Queues a new analysis using the saved settings from an earlier job.

Example:

rootcoz re-analyze job-123

Return value/effect: Queues a new analysis and prints the new job_id, status, and result URL.

status

Shows the current state of one analysis job.

Example:

rootcoz status job-123

Return value/effect: Default output is a two-column table with job_id and status. JSON mode returns the full stored result payload.

results list

Lists recent analysis jobs.

Example:

rootcoz results list --limit 10

Return value/effect: Prints a table with job_id, status, jenkins_url, and created_at.

results dashboard

Lists analysis jobs with dashboard metadata.

Example:

rootcoz results dashboard

Return value/effect: Prints a table with job_id, job_name, build_number, status, failure_count, reviewed_count, comment_count, and created_at.

results show

Shows one stored analysis result.

Example:

rootcoz results show job-123

Return value/effect: Default output is a summary table with job_id, status, summary, failures, children, ai_provider, and created_at. --full prints the full result JSON.

results delete

Deletes one or more stored analysis jobs.

Warning: --all requires --confirm and cannot be combined with explicit job IDs.

Example:

rootcoz results delete job-123 job-124

Return value/effect: Deletes the requested job IDs. Single-job runs print one confirmation line; multi-job runs print a success summary and any failures.

results review-status

Shows review progress for one result set.

Example:

rootcoz results review-status job-123

Return value/effect: Prints a table with total_failures, reviewed_count, and comment_count.

results set-reviewed

Sets or clears the reviewed state for one failure.

Warning: --child-build must be non-negative. Values greater than 0 require --child-job.

Example:

rootcoz results set-reviewed job-123 --test tests.TestA.test_one --reviewed

Return value/effect: Prints a short confirmation line, including the reviewer name when the server returns it.

results enrich-comments

Refreshes stored comment links with live tracker state.

Example:

rootcoz results enrich-comments job-123

Return value/effect: Refreshes linked PR and ticket state for the job's comments and prints a completion line.

ai-configs

Lists AI provider/model pairs found in completed analyses.

Example:

rootcoz ai-configs

Return value/effect: Prints a table with ai_provider and ai_model. If no completed analyses contributed configurations, it prints an empty-state message.

ai-models

Lists currently available models by AI provider.

Example:

rootcoz ai-models --provider claude

Return value/effect: With --provider, prints the models for that provider. Without it, prints one section per provider with a model count and id/name rows.

History and Classification

Tip: See Exploring Failure History and Test Trends and Reviewing and Classifying Failures for workflow guidance.

history test

Shows failure history for one fully qualified test name.

Example:

rootcoz history test tests.TestA.test_one --limit 10

Return value/effect: Prints summary lines for the test, then a Recent runs table and a Comments table when those sections are present.

history search

Finds tests that share one error signature.

Example:

rootcoz history search --signature 2f0c8d0c...

Return value/effect: Prints the signature, total occurrence count, unique test count, and a table of matching tests.

history stats

Shows aggregate history statistics for one Jenkins job.

Example:

rootcoz history stats ocp-e2e-aws

Return value/effect: Prints job-level totals and, when available, a Most common failures table.

history failures

Lists paginated failure history across jobs.

Example:

rootcoz history failures --classification "PRODUCT BUG" --limit 25

Return value/effect: Prints a total-count line followed by a table with test_name, job_name, classification, and analyzed_at.

classify

Creates a classification for one failure.

Example:

rootcoz classify tests.TestA.test_one --type FLAKY --job-id job-123 --reason "Intermittent DNS lookup"

Return value/effect: Creates a classification record and prints its server-generated ID.

classifications list

Lists stored classifications.

Example:

rootcoz classifications list --type FLAKY --job-name ocp-e2e-aws

Return value/effect: Prints a table with test_name, classification, reason, created_by, and created_at. If nothing matches, it prints an empty-state message.

override-classification

Overrides one failure's top-level classification.

Example:

rootcoz override-classification job-123 --test tests.TestA.test_one --classification "PRODUCT BUG"

Return value/effect: Updates the stored classification and prints the final value returned by the server.

Comments and Mentions

Tip: See Commenting and Mentioning Teammates for workflow guidance.

comments list

Lists comments for one analysis job.

Example:

rootcoz comments list job-123

Return value/effect: Prints a table with id, test_name, comment, username, and created_at. If the job has no comments, it prints an empty-state message.

comments add

Adds a comment to one failure.

Example:

rootcoz comments add job-123 --test tests.TestA.test_one --message "Opened PROJ-456"

Return value/effect: Creates the comment and prints the new comment ID.

comments delete

Deletes one comment.

Example:

rootcoz comments delete job-123 42

Return value/effect: Deletes the comment and prints a confirmation line.

mentionable-users

Lists usernames that can be mentioned in comments.

Example:

rootcoz mentionable-users

Return value/effect: Prints one username per line. If no users are available, it prints an empty-state message.

mentions

Lists the current user's mentions.

Example:

rootcoz mentions --unread

Return value/effect: Prints the total and unread counts, then a table with id, job_id, test_name, comment, username, is_read, and created_at.

mentions-mark-read

Marks selected mentions as read.

Example:

rootcoz mentions-mark-read --ids 10,11,12

Return value/effect: Marks the listed mentions as read and exits successfully when the server accepts the request.

mentions-mark-all-read

Marks every mention for the current user as read.

Example:

rootcoz mentions-mark-all-read

Return value/effect: Marks all mentions as read and exits successfully when the server accepts the request.

analyze-comment-intent

Runs AI intent detection on one comment string.

Example:

rootcoz analyze-comment-intent "Fixed in PR #42"

Return value/effect: Prints whether the comment suggests the failure is reviewed and, when present, the returned reason string.

Issue and Integration Commands

Tip: See Creating GitHub and Jira Issues for issue workflows and Connecting GitHub, Jira, and Report Portal for setup details.

capabilities

Shows server-side automation feature flags.

Example:

rootcoz capabilities

Return value/effect: Prints a JSON object that reports whether GitHub issue creation and Jira bug creation are enabled on the server.

jira-projects

Lists Jira projects available to the current credentials.

Example:

rootcoz jira-projects --query platform

Return value/effect: Prints a table with project key and name. If no projects match, it prints an empty-state message.

jira-security-levels

Lists Jira security levels for one project.

Example:

rootcoz jira-security-levels PROJ

Return value/effect: Prints a table with security level name and description. If the project exposes none, it prints an empty-state message.

preview-issue

Generates issue content for GitHub or Jira without creating the issue.

Warning: --type accepts only github or jira.

Note: GitHub-only overrides are used only when --type github is selected. Jira-only overrides are used only when --type jira is selected.

Core options

Tracker override options

Example:

rootcoz preview-issue job-123 --test tests.TestA.test_one --type github --include-links

Return value/effect: Prints the generated issue title and body. When the server returns related matches, it also prints a Similar issues section.

get-issue-prompt

Shows the issue-generation prompt associated with one analysis job.

Example:

rootcoz get-issue-prompt job-123

Return value/effect: Prints the stored prompt text. If the job has no issue prompt, it prints an empty-state message.

create-issue

Creates a GitHub issue or Jira issue from an analyzed failure.

Warning: --type accepts only github or jira.

Core options

Tracker override options

Example:

rootcoz create-issue \
  job-123 \
  --test tests.TestA.test_one \
  --type jira \
  --title "DNS timeout in tests.TestA.test_one" \
  --body "Observed in build 1542." \
  --jira-issue-type Bug

Return value/effect: Creates the issue, then prints the created key or number, the issue URL, and an added comment ID when the server returns one.

validate-token

Validates a GitHub or Jira token.

Warning: Invalid tokens exit with status code 1, including JSON mode.

Example:

rootcoz validate-token github --token "$GITHUB_TOKEN"

Return value/effect: Prints a valid or invalid status line. In JSON mode, it prints the validation response object.

push-reportportal

Pushes stored classifications into Report Portal.

Note: Alias: push-rp.

Example:

rootcoz push-reportportal job-123 --child-job-name my-child --child-build-number 42

Return value/effect: Prints the number of pushed classifications, the launch ID when returned, any unmatched tests, and any error count/details.

Authentication and Admin Commands

Tip: See Managing Users and API Keys and Updating Your Profile and Notifications for workflow guidance.

auth login

Validates admin credentials.

Note: This command does not persist a login session across later CLI invocations. Persistent admin access is normally provided by the global --api-key, ROOTCOZ_API_KEY, or a profile api_key.

Example:

rootcoz auth login --username admin --api-key "$ROOTCOZ_ADMIN_KEY"

Return value/effect: Prints the returned username, role, and admin flag.

auth logout

Sends the logout request.

Example:

rootcoz auth logout

Return value/effect: Sends the logout request and exits successfully when the server accepts it.

auth whoami

Shows the current authenticated user record.

Example:

rootcoz auth whoami

Return value/effect: Prints a table with username, role, and is_admin.

admin users list

Lists known users.

Example:

rootcoz admin users list

Return value/effect: Prints a table with username, role, created_at, and last_seen.

admin users create

Creates a new admin account.

Warning: The generated API key is shown once. Save it before the command ends.

Example:

rootcoz admin users create release-admin

Return value/effect: Creates the account and prints the returned API key.

admin users delete

Removes an admin account by username.

Example:

rootcoz admin users delete release-admin --force

Return value/effect: Deletes the named account. Without --force, the CLI asks for confirmation first.

admin users rotate-key

Rotates an admin user's API key.

Warning: The new API key is shown once. Save it before the command ends.

Example:

rootcoz admin users rotate-key release-admin

Return value/effect: Rotates the key and prints the newly issued API key.

admin users change-role

Changes a user's role.

Warning: Promoting a user to admin can return a new API key. Save it before the command ends.

Example:

rootcoz admin users change-role alice admin

Return value/effect: Updates the user's role and prints the returned role. When the server returns a new admin key, the CLI prints it.

admin token-usage

Shows AI token usage and cost data.

Mode selection

Note: --json overrides --format.

Example:

rootcoz admin token-usage --group-by provider --format csv

Return value/effect: In text mode, prints either a dashboard summary, aggregated totals, or per-job call records. CSV mode prints CSV rows. JSON mode prints the raw response object.

Metadata Commands

metadata list

Lists stored job metadata.

Example:

rootcoz metadata list --team platform --label nightly

Return value/effect: Prints a table with job_name, team, tier, version, and labels.

metadata get

Shows metadata for one job.

Example:

rootcoz metadata get ocp-e2e-aws

Return value/effect: Prints one row with job_name, team, tier, version, and labels.

metadata set

Creates or updates metadata for one job.

Example:

rootcoz metadata set ocp-e2e-aws --team platform --tier critical --label nightly

Return value/effect: Updates the job metadata and prints a confirmation line naming the job.

metadata delete

Deletes metadata for one job.

Example:

rootcoz metadata delete ocp-e2e-aws

Return value/effect: Deletes the metadata record and prints a confirmation line naming the job.

metadata import

Bulk imports job metadata from a local file.

Warning: .yaml and .yml files are parsed as YAML. Any other extension is parsed as JSON. The file must contain an array of metadata objects.

Example:

rootcoz metadata import ./metadata.yaml

Return value/effect: Reads the local file, uploads the parsed items, and prints the number of updated metadata entries.

metadata rules

Lists configured metadata auto-assignment rules.

Example:

rootcoz metadata rules

Return value/effect: Prints the rules file path when present, then each rule's pattern and assigned fields. If no rules are configured, it prints an empty-state message.

metadata preview

Shows what metadata rules would assign to one job name.

Example:

rootcoz metadata preview test-smoke

Return value/effect: Prints the matched metadata fields for that job name, or an empty-state message when no rule matches.

Configuration Commands

Note: rootcoz config runs rootcoz config show when no subcommand is given.

Note: Configuration commands do not require a server connection.

Tip: See Configuration Reference for field-by-field config details.

config show

Shows the current config file summary.

Example:

rootcoz config show

Return value/effect: Prints the config file path, default server name, and configured servers. If no config file exists, it prints the expected path and a starter file snippet.

config completion

Prints shell-completion setup instructions.

Example:

rootcoz config completion bash

Return value/effect: Prints the shell RC snippet that calls rootcoz --show-completion SHELL. Unsupported shell names exit with an error.

config servers

Lists configured server profiles.

Example:

rootcoz config servers

Return value/effect: Prints a table with name, url, username, no_verify_ssl, and a default-server marker. JSON mode returns an object keyed by server name.

Related Pages

• Automating Common Tasks with the CLI
• Configuration Reference
• API Endpoint Reference
• Submitting Jenkins Builds and JUnit XML
• Reviewing and Classifying Failures