CLI Usage Reference

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

Development Cycle

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

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.

Get Started

CLI Commands

Integrations

CLI Usage Reference

Global Options

Commands Overview

Project Initialization

`bugster init`

Initialize Bugster in your project

Test Generation & Analysis

`bugster generate`

Generate Tests from Codebase

Test Execution

`bugster run`

Execute Bugster Tests

Test Maintenance

`bugster update`

Synchronize Test Changes

Remote Synchronization

`bugster sync`

Sync with Remote Platform

Common Workflows

Configuration

Configuration Files

Directory Structure

Configuration Options

Troubleshooting

Dependencies

Next Steps

Installation Guide

API Reference

Get Started

CLI Commands

Integrations

​Global Options

​Commands Overview

​Project Initialization

​bugster init

Initialize Bugster in your project

​Test Generation & Analysis

​bugster generate

Generate Tests from Codebase

​Test Execution

​bugster run

Execute Bugster Tests

​Test Maintenance

​bugster update

Synchronize Test Changes

​Remote Synchronization

​bugster sync

Sync with Remote Platform

​Common Workflows

​Configuration

Configuration Files

​Directory Structure

​Configuration Options

​Troubleshooting

​Dependencies

​Next Steps

Installation Guide

API Reference

Global Options

Commands Overview

Project Initialization

`bugster init`

Test Generation & Analysis

`bugster generate`

Test Execution

`bugster run`

Test Maintenance

`bugster update`

Remote Synchronization

`bugster sync`

Common Workflows

Configuration

Directory Structure

Configuration Options

Troubleshooting

Dependencies

Next Steps