CLI Usage Reference

Complete reference guide for all Bugster CLI commands and options

For help with any command, use bugster [command] --help to see detailed options and usage information.

Global Options

The following options are available for all Bugster CLI commands:

• --version, -v - Print the version and exit
• --help, -h - Show help message

Commands Overview

The Bugster CLI provides a comprehensive set of commands for project setup, test generation, execution, and synchronization. Here are all available commands:

Project Initialization

bugster init

Initialize Bugster in your project

Set up your project and authenticate with Bugster. This is the first command you should run.

bugster init

What it does:

• Prompts you to enter your Bugster API key
• Validates the API key with Bugster servers
• Stores authentication credentials for future use
• Creates .bugster directory in your project root
• Sets up configuration files (config.yaml)
• Initializes project-specific settings
• Prepares your project for test generation and execution
• Creates initial directory structure for tests and cache

Example output structure:

.bugster/
├── config.yaml      # Project configuration
├── tests/          # Generated test specifications
└── cache/          # Analysis cache files

You must run init to authenticate before using other Bugster CLI features that require API access.

---

Test Generation & Analysis

bugster generate

Generate Tests from Codebase

Analyze your codebase to automatically generate comprehensive test specifications.

bugster generate [OPTIONS]

Options:

• --show-logs - Show detailed logs during the analysis process
• --force, -f - Force analysis even if codebase has already been analyzed (overrides cache)

What it does:

• Scans your codebase to understand application structure
• Identifies testable components and functionality
• Generates comprehensive test specifications using AI
• Creates test files in the .bugster/tests directory
• Uses intelligent code pattern recognition

Examples:

# Basic test generation
bugster generate

# Generate tests with detailed logging
bugster generate --show-logs

# Force re-analysis of already analyzed codebase
bugster generate --force

Example generated test:

- name: Checkout Process Test
  task: Verify that users can complete the checkout process
  expected_result: Order should be successfully placed
  steps:
    - Navigate to /products page
    - Add a product to the cart
    - Navigate to /cart page
    - Verify product is in the cart
    - Click "Proceed to Checkout" button
    - Fill in shipping information
    - Select shipping method
    - Enter payment information
    - Review order summary
    - Click "Place Order" button
    - Verify order confirmation page is displayed

---

Test Execution

bugster run

Execute Bugster Tests

Run your Bugster tests with various execution modes and output options.

bugster run [PATH] [OPTIONS]

Arguments:

• PATH - Optional path to test file or directory (defaults to .bugster/tests)

Options:

• --headless - Run tests in headless mode (for browser-based tests)
• --silent, -s - Run in silent mode with less verbose output
• --stream-results - Stream test results as they complete (real-time output)
• --output FILE - Save test results to a JSON file
• --run-id ID - Associate a specific run ID with the test execution
• --base-url URL - Override the base URL for the test run

Examples:

# Run all tests
bugster run

# Run tests in headless mode
bugster run --headless

# Run specific test file silently
bugster run tests/login.spec.js --silent

# Run with real-time output and save results
bugster run --stream-results --output results.json

# Run tests against staging environment
bugster run --base-url https://staging.example.com

# Run specific test directory with custom run ID
bugster run integration_tests/ --run-id "release-v1.2.3"

What happens during execution:

• Loads configuration from .bugster/config.yaml
• Finds and loads test files (YAML/JSON format)
• For each test case, the Bugster Agent:
  • Opens a browser and performs test steps
  • Executes each step in sequence
  • Validates results against expected outcomes
  • Determines pass/fail status
• Displays summary table with results (Test Name, Result, Reason, Time)
• Exits with error code if any tests fail

---

Test Maintenance

bugster update

Synchronize Test Changes

Update your test specifications based on the latest changes in your codebase.

bugster update [OPTIONS]

Options:

• --update-only - Only update existing specs, skip suggestions and deletions
• --suggest-only - Only suggest new specs, skip updates and deletions
• --delete-only - Only delete obsolete specs, skip updates and suggestions
• --show-logs - Show detailed logs during the update process

What it does:

• Detects changes in your codebase since last analysis
• Updates existing test specifications to match code changes
• Suggests new tests for new functionality
• Identifies and removes obsolete test specifications
• Maintains test coverage as your code evolves

Examples:

# Full update: modify, suggest, and delete specs
bugster update

# Only update existing test specifications
bugster update --update-only

# Only suggest new tests with logging
bugster update --suggest-only --show-logs

# Only remove obsolete specifications
bugster update --delete-only

---

Remote Synchronization

bugster sync

Sync with Remote Platform

Synchronize your local test specifications with the remote Bugster platform for team collaboration.

bugster sync [OPTIONS]

Options:

• --branch BRANCH - Specify branch to sync with (defaults to current git branch or ‘main’)
• --pull - Only pull specs from remote (download only)
• --push - Only push specs to remote (upload only)
• --clean-remote - Delete remote specs that don’t exist locally
• --dry-run - Show what would happen without making actual changes
• --prefer CHOICE - Prefer ‘local’ or ‘remote’ when resolving conflicts

What it does:

• Synchronizes test specifications between local and remote
• Handles branch-specific test data
• Resolves conflicts between local and remote versions
• Enables team collaboration on test specifications
• Provides backup and versioning for your test data

Examples:

# Full bidirectional sync
bugster sync

# Sync with specific branch
bugster sync --branch feature/new-ui

# Only download specs from remote
bugster sync --pull

# Preview upload without making changes
bugster sync --push --dry-run

# Resolve conflicts preferring local versions
bugster sync --prefer local

# Clean up remote specs not present locally
bugster sync --clean-remote

---

Common Workflows

Getting Started

# 1. Initialize project and authenticate (FIRST STEP)
bugster init

# 2. Generate initial test specs
bugster generate

# 3. Run the generated tests
bugster run

Development Cycle

# 1. Make code changes
# [Your development work]

# 2. Update tests for code changes
bugster update

# 3. Verify tests still pass
bugster run

# 4. Sync with team/remote
bugster sync

Team Collaboration

# 1. Get latest team test specs
bugster sync --pull

# 2. Work on features
# [Your development work]

# 3. Update tests for your changes
bugster update

# 4. Share your test updates
bugster sync --push

Debugging Failed Tests

# 1. Run tests with detailed logging
bugster run --show-logs

# 2. Run specific failing test
bugster run path/to/failing_test.yml --stream-results

# 3. Check test in non-headless mode
bugster run path/to/failing_test.yml

# 4. Save results for analysis
bugster run --output debug_results.json

---

Configuration

Configuration Files

Bugster stores all configuration and test data in the .bugster/ directory.

Directory Structure

.bugster/
├── config.yaml          # Project configuration
│   ├── base_url         # Application URL
│   ├── credentials      # Authentication data
│   └── project_settings # Project-specific options
├── tests/               # Generated test specifications
│   ├── smoke_tests/     # Smoke test suite
│   ├── integration/     # Integration tests
│   └── e2e/            # End-to-end tests
└── cache/              # Analysis cache files
    ├── codebase_hash   # Codebase state tracking
    └── analysis_data   # Cached analysis results

Configuration Options

The config.yaml file contains:

• base_url: Default URL for running tests
• credentials: Authentication information
• project_settings: Custom project configurations
• test_directories: Custom test organization
• execution_preferences: Default test execution settings

---

Troubleshooting

Common Issues

Authentication Problems:

• If you entered an incorrect API key, run bugster init again to re-authenticate.
• Check network connectivity to Bugster servers

Configuration Issues:

• Check .bugster/config.yaml for syntax errors
• Reinitialize if corrupted: bugster init

Test Execution Failures:

• Use --show-logs for detailed debugging information
• Verify base URL is accessible: --base-url option
• Check browser dependencies for headless mode

Debug Commands

# Get detailed logs during any operation
bugster [command] --show-logs

# Preview sync changes without applying
bugster sync --dry-run

# Force bypass cache issues
bugster generate --force

# Run tests with full output
bugster run --stream-results

Reset and Recovery

# Reinitialize project (this also allows re-authentication)
bugster init

# Force regenerate all tests
bugster generate --force

# Clean remote sync state
bugster sync --clean-remote --dry-run  # preview first
bugster sync --clean-remote           # then execute

---

Dependencies

Bugster CLI relies on several Python packages for optimal functionality.

Key Dependencies:

• click - Command-line interface framework
• httpx - HTTP client for API communication
• pydantic - Data validation and parsing
• rich - Rich text and beautiful formatting
• typer - Modern CLI framework

All dependencies are automatically managed during installation. For a complete list, refer to the requirements.txt file in the project repository.

---

Next Steps

Installation Guide

Install Bugster CLI on your system

API Reference

Explore the API integration options