CLI Usage Reference

​

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

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

​

Test Generation & Analysis

​

bugster generate

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

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

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

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

​

Configuration

​

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

​

Dependencies

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

​

Next Steps