Imported from MindscapeHQ/raygun-cli (AGENTS.md). Install upstream with npx skills add MindscapeHQ/raygun-cli. Copyright stays with the author.

Raygun CLI - Agent Guide

Build/Test Commands

dart pub get --enforce-lockfile - Install dependencies from the committed lockfile
dart test - Run all tests
dart test test/config_props_test.dart - Run single test file
dart analyze - Run linter/analysis (uses package:lints/recommended.yaml)
dart compile exe bin/raygun_cli.dart -o raygun-cli - Build executable
dart run bin/raygun_cli.dart - Run CLI locally
dart format . - Format code
dart run build_runner build - Generate mocks (one-time)
dart run build_runner watch - Auto-regenerate mocks on changes

Architecture

CLI Tool: Uploads sourcemaps, manages obfuscation symbols, tracks deployments for Raygun.com
Main Entry: bin/raygun_cli.dart - CLI argument parsing and command routing
Commands: lib/src/ - Five main command modules: sourcemap, symbols, deployments, proguard, dsym
APIs: Each command has corresponding API client (*_api.dart) for Raygun REST API calls
Config: config_props.dart handles arg parsing with env var and .env file fallbacks (RAYGUN_APP_ID, RAYGUN_TOKEN, RAYGUN_API_KEY). Resolution order: CLI arg > env var > .env file. Empty and whitespace-only values at any tier are treated as missing and fall through. With -v/--verbose, each property's resolved source is logged. See lib/src/config_file.dart for .env discovery logic — discovery walks up from CWD, stopping at $HOME/%USERPROFILE%; if neither is set, discovery is restricted to CWD only.

Directory Structure

lib/src/[command]/
  ├── [command]_command.dart  # CLI parsing and routing
  ├── [command]_api.dart      # Raygun API integration
  └── [command].dart          # Business logic (if complex)
lib/src/core/                 # Shared utilities (RaygunCommand, RaygunApi builders)
test/[command]/               # Tests mirror lib structure

Dependency Flow

bin/raygun_cli.dart → lib/src/[command]/[command]_command.dart → *_api.dart

Commands are stateless; API clients handle HTTP
Commands receive API clients via constructor (dependency injection)

Code Style

Imports: Standard library first, then package imports, then relative imports
Naming: Snake_case for files/dirs, camelCase for variables, PascalCase for classes
Functions: Use Future<bool> for async operations, return success/failure status
Errors: Print error messages to console, return false on failure
Types: Use explicit types for public APIs, required named parameters preferred
Strings: Use single quotes, string interpolation with $variable or ${expression}
Comments: Use /// for public API documentation, avoid inline comments

Error Handling & Exit Codes

Standard error handling patterns used throughout:

Exit code 0: Success
Exit code 1: Failure (operation didn't succeed)
Exit code 2: Error (exception or invalid input)
Print errors to console before returning/exiting
Use Future<bool> return type for async operations
Chain with .then() and .catchError() for error handling

Example:

run().then((result) {
  if (result) {
    exit(0);
  } else {
    exit(2);
  }
}).catchError((e) {
  print('Error: $e');
  exit(2);
});

Command Implementation Patterns

All commands extend the RaygunCommand abstract class:

Required Implementation

class MyCommand extends RaygunCommand {
  const MyCommand({required this.api});

  final MyApi api;

  @override
  String get name => 'mycommand';

  @override
  ArgParser buildParser() { /* ... */ }

  @override
  void execute(ArgResults command, bool verbose) { /* ... */ }
}

Command Patterns

Help Flag: Always check for --help flag first and exit(0)
Config Loading: Use ConfigProp.load() for app-id, token, api-key (exits if missing)
Subcommands: Use ArgParser.addCommand() (see symbols: upload/list/delete)
Verbose Flag: Available in all commands (inherited from main parser)
Mandatory Args: Use mandatory: true in ArgParser for required flags

Example: Subcommands Pattern (symbols command)

ArgParser buildParser() {
  return ArgParser()
    ..addOption('app-id')
    ..addOption('token')
    ..addCommand('upload')
    ..addCommand('list')
    ..addCommand('delete');
}

API Client Patterns

Each command has a corresponding API client:

Builder Pattern for Requests

RaygunMultipartRequestBuilder - For file uploads
RaygunPostRequestBuilder - For JSON POST requests

Example:

final request = RaygunMultipartRequestBuilder(url, 'POST')
  .addBearerToken(token)
  .addFile('file', filePath)
  .addField('version', version)
  .build();

API Client Structure

Factory method pattern: Use static .create() for production instances
Return Future<bool> to indicate success/failure
Print response codes and messages for debugging
Handle HTTP responses and errors appropriately

Testing Patterns & Mock Generation

Test Structure

Tests use mockito for mocking API clients
Test files mirror lib/ structure (e.g., lib/src/symbols/ → test/symbols/)
Mock files use .mocks.dart suffix and are git-tracked
Generate mocks with: dart run build_runner build

Test Pattern

// 1. Generate mock classes with @GenerateMocks annotation
@GenerateMocks([MyApi])
void main() {
  group('MyCommand', () {
    late MockMyApi mockApi;

    setUp(() {
      mockApi = MockMyApi();
    });

    test('description', () async {
      // 2. Setup mock behavior
      when(mockApi.someMethod()).thenAnswer((_) async => true);

      // 3. Inject mock into command
      final command = MyCommand(api: mockApi);

      // 4. Execute and verify
      final result = await command.run(...);
      expect(result, true);
    });
  });
}

Mock Regeneration

After changing API signatures, run: dart run build_runner build
Use watch mode during development: dart run build_runner watch

Dependency Injection

Pattern

Commands receive API clients via constructor
Global command instances use .create() factories
Tests inject mock API clients
Enables testing without hitting real APIs

Example:

// Production usage (in command file)
SymbolsCommand symbolsCommand = SymbolsCommand(api: SymbolsApi.create());

// Test usage
final mockApi = MockSymbolsApi();
final command = SymbolsCommand(api: mockApi);

CI/CD & Release Workflow

PR Requirements

Title: Must follow Conventional Commits (enforced by .github/workflows/pr.yml)
Checks: All must pass - enforced lockfile install, format, analyze, test
Platforms: Multi-platform builds run automatically (Linux, macOS, Windows)

Lockfile and Supply-Chain Policy

pubspec.lock is intentionally committed because this repository builds a CLI executable and release binaries.
Use dart pub get --enforce-lockfile in CI, release workflows, and source-build verification. This fails when the lockfile is missing, out of sync with pubspec.yaml, or package content hashes do not match.
Dependency updates should be isolated to dependency-specific PRs, usually from Dependabot. Review pubspec.lock changes alongside any pubspec.yaml changes.
Do not broad-upgrade unrelated dependencies in feature or fix PRs unless needed for the task.
CI build artifacts include the compiled binary, pubspec.lock, and SHA256SUMS.
Release archives include the platform binary, pubspec.lock, build-manifest.txt, and SHA256SUMS so users can verify and reproduce builds from the tagged commit.

Conventional Commits Format

Examples:

feat: add new command for X
fix: resolve issue with Y
chore: update dependencies
docs: update README

Version Management

IMPORTANT: Update BOTH files when releasing:

pubspec.yaml - version field
bin/raygun_cli.dart - version constant

Workflows

pr.yml: Validates PR title format
main.yml: Enforces the lockfile, runs tests, format check, analysis, builds binaries for all platforms, and uploads binaries with lockfile/checksums
release.yml: On GitHub release, enforces the lockfile, builds zipped binaries, and includes lockfile/checksum/build-manifest files in each archive

Development Workflow

Local Testing

# Run CLI locally with arguments
dart run bin/raygun_cli.dart <command> <args>

# Use verbose flag for debug output
dart run bin/raygun_cli.dart -v sourcemap --help

# Set environment variables for testing
export RAYGUN_APP_ID=test-app-id
export RAYGUN_TOKEN=test-token
export RAYGUN_API_KEY=test-api-key

Testing Workflow

Write/modify API client code
Add @GenerateMocks([MyApi]) to test file
Run dart run build_runner build to generate mocks
Write tests using mock instances
Run dart test to verify

Build for Distribution

# Compile for current platform
dart pub get --enforce-lockfile
dart compile exe bin/raygun_cli.dart -o raygun-cli

# Note: Cross-compilation not supported; use CI for other platforms

Common Gotchas & Best Practices

Validation Order

Always validate --help flag first before parsing other args
ConfigProp.load() calls exit(2) if required config is missing
Check mandatory args before executing business logic

File Operations

Use File.existsSync() before file operations
Throw descriptive exceptions if files don't exist
Use .split("/").last to get filename from path

Argument Parsing

Use command.wasParsed('flag') to check if flag was provided
Use command['option'] to get option value
Use command.command?.name to get subcommand name

Async Patterns

Prefer .then() and .catchError() over try/catch for CLI commands
Always handle errors gracefully with user-friendly messages
Use Future<bool> for operations that can succeed or fail

String Conventions

Always use single quotes for strings (Dart convention)
Use string interpolation: 'Value: $variable' or 'Value: ${expression}'

Quick Reference

Command Examples

# Sourcemap upload (Flutter)
dart run bin/raygun_cli.dart sourcemap -p flutter \
  --uri=https://example.com/main.dart.js \
  --app-id=XXX --token=YYY

# Sourcemap upload (single file)
dart run bin/raygun_cli.dart sourcemap \
  --input-map=path/to/index.js.map \
  --uri=https://example.com/index.js \
  --app-id=XXX --token=YYY

# Symbols upload
dart run bin/raygun_cli.dart symbols upload \
  --path=app.android-arm64.symbols \
  --version=1.0.0 \
  --app-id=XXX --token=YYY

# Symbols list
dart run bin/raygun_cli.dart symbols list \
  --app-id=XXX --token=YYY

# Symbols delete
dart run bin/raygun_cli.dart symbols delete \
  --id=2c7a3u3 \
  --app-id=XXX --token=YYY

# Deployments tracking
dart run bin/raygun_cli.dart deployments \
  --version=1.0.0 \
  --token=YYY \
  --api-key=ZZZ \
  --scm-type=GitHub \
  --scm-identifier=abc123

# Proguard upload
dart run bin/raygun_cli.dart proguard \
  --app-id=XXX \
  --version=1.0.0 \
  --path=mapping.txt \
  --external-access-token=EAT \
  --overwrite

# iOS dSYM upload
dart run bin/raygun_cli.dart dsym \
  --app-id=XXX \
  --path=path/to/dsym.zip \
  --external-access-token=EAT

Environment Variables

export RAYGUN_APP_ID=your-app-id
export RAYGUN_TOKEN=your-token
export RAYGUN_API_KEY=your-api-key

`.env` Config File

The same keys are also read from a .env file in the current working directory (or any parent directory, walking up to $HOME/%USERPROFILE%). When neither HOME nor USERPROFILE is set (sandboxed CI runners, minimal containers), discovery is restricted to CWD only — no upward walking. An explicit path can always be passed with --config-file=<path>.

# .env
RAYGUN_APP_ID=your-app-id
RAYGUN_TOKEN=your-token
RAYGUN_API_KEY=your-api-key

Resolution precedence: CLI argument > environment variable > .env file. Empty (KEY=) and whitespace-only (KEY=" ") values at any tier are treated as missing and fall through to the next source — this prevents opaque HTTP 4xx errors when a user has copied the example .env and forgotten to fill in a value. Use -v/--verbose to print which source supplied each value.

A sample is committed at example/.env.example.

Known TODOs & Future Improvements

NodeJS sourcemap platform support (currently stubbed in sourcemap command)
System package manager installations (brew, apt, etc.)

Troubleshooting

Mock Generation Issues

Ensure @GenerateMocks annotation is present in test file
Run dart pub get --enforce-lockfile to ensure dependencies are installed from the committed lockfile
Clean and rebuild: dart run build_runner clean && dart run build_runner build

Build Issues

Ensure Dart SDK version matches pubspec.yaml requirement (^3.11.0)
Run dart pub get --enforce-lockfile to verify the committed lockfile is usable
For intentional dependency updates, update pubspec.yaml if needed, run dart pub upgrade <package>, and commit the resulting pubspec.lock
Check that version in bin/raygun_cli.dart matches pubspec.yaml

Test Failures

Verify mocks are regenerated after API changes
Check that mock behavior is properly stubbed with when()
Ensure async tests use async/await or return Future

About

Raygun CLI - Agent Guide

Build/Test Commands

Architecture

Directory Structure

Dependency Flow

Code Style

Error Handling & Exit Codes

Command Implementation Patterns

Required Implementation

Command Patterns

Example: Subcommands Pattern (symbols command)

API Client Patterns

Builder Pattern for Requests

API Client Structure

Testing Patterns & Mock Generation

Test Structure

Test Pattern

Mock Regeneration

Dependency Injection

Pattern

CI/CD & Release Workflow

PR Requirements

Lockfile and Supply-Chain Policy

Conventional Commits Format

Version Management

Workflows

Development Workflow

Local Testing

Testing Workflow

Build for Distribution

Common Gotchas & Best Practices

Validation Order

File Operations

Argument Parsing

Async Patterns

String Conventions

Quick Reference

Command Examples

Environment Variables

.env Config File

Known TODOs & Future Improvements

Troubleshooting

Mock Generation Issues

Build Issues

Test Failures

Use it

Manifest

Reviews

`.env` Config File