matimo-bruno

Bruno CLI tools for Matimo — Enable AI agents to autonomously manage, execute, and validate API test collections.

📦 Installation

pip install matimo-bruno

🚀 Quick Start

Python

from matimo import Matimo

matimo = await Matimo.init()

# List all collections in workspace
collections = await matimo.execute('bruno_list_collections', {
    'workspace_path': './collections'
})

# Get collection metadata before running
info = await matimo.execute('bruno_get_collection_info', {
    'collection_path': './collections/payment-api'
})

# Run entire collection
result = await matimo.execute('bruno_run_collection', {
    'collection_path': './collections/payment-api',
    'environment': 'staging',
    'report_path': './reports/staging-results.json'
})

# Run single request for debugging
response = await matimo.execute('bruno_run_request', {
    'collection_path': './collections/auth',
    'request_name': 'Login',
    'environment': 'staging'
})

# Bootstrap from OpenAPI spec
imported = await matimo.execute('bruno_import_openapi', {
    'spec_source': 'https://api.example.com/openapi.json',
    'output_directory': './collections',
    'collection_name': 'Generated API Tests'
})

# Create new collection
created = await matimo.execute('bruno_create_collection', {
    'collection_path': './collections/new-service',
    'collection_name': 'New Service Tests'
})

📋 Available Tools

1. bruno_run_collection

Execute a Bruno API collection with configurable environments, data files, and reporting.

Parameters:

• collection_path (required) — Path to collection file or directory
• environment — Environment name (dev, staging, prod)
• env_file — Path to environment file override
• data_file — CSV/JSON data file for data-driven testing
• iteration_count — Number of iterations to run
• delay_ms — Delay between requests
• tags — Comma-separated tags (run requests with ALL tags)
• exclude_tags — Comma-separated tags (skip requests with ANY tags)
• tests_only — Run only requests with tests/assertions
• bail_on_failure — Stop on first failure
• parallel — Run requests in parallel
• sandbox_mode — JavaScript execution mode ('safe' or 'developer')
• report_format — Report format (json, junit, html)
• report_path — Path to write report file

Returns: Collection execution results, summary, and report path

2. bruno_run_request

Execute a single request for targeted debugging and validation.

Parameters:

• collection_path (required) — Collection directory
• request_name (required) — Request name to execute
• environment — Environment name override
• env_file — Environment file override
• sandbox_mode — JavaScript execution mode

Returns: Request/response details and assertion results

3. bruno_list_collections

Discover all collections in a workspace.

Parameters:

• workspace_path (required) — Workspace directory
• filter — Filter by collection name (substring)

Returns: Array of collection metadata

4. bruno_get_collection_info

Introspect collection structure before execution.

Parameters:

• collection_path (required) — Collection path

Returns: Collection structure, requests, environments, variables

5. bruno_import_openapi

Bootstrap a collection from OpenAPI 3.0 specification.

Parameters:

• spec_source (required) — Path or URL to OpenAPI spec
• output_directory (required) — Where to create collection
• collection_name — Collection name
• collection_format — 'bru' or 'opencollection'
• group_by — Group by 'tags' or 'path'
• insecure — Skip TLS verification

Returns: Collection path and metadata

6. bruno_create_collection

Create a new empty collection scaffold.

Parameters:

• collection_path (required) — Collection creation path
• collection_name (required) — Collection name

Returns: Creation status and path

🔄 Agent Workflows

Autonomous Test Execution

Agent discovers spec → import_openapi → set environment → run_collection → parse results

Multi-Environment Validation

list_collections → for each environment: set_env + run_collection → compare results

Targeted Debugging

get_collection_info → run_request (single endpoint) → analyze response

Data-Driven Testing

run_collection with CSV file → multiple iterations → aggregate metrics

🔐 Authentication

Tools use environment variables for credentials. Bruno CLI manages environment setup — tools wrap CLI execution.

📖 Prerequisites

• Bruno CLI installed globally: pnpm install -g @usebruno/cli
• Python 3.11+
• Bruno collections in .bru format or OpenAPI specs

🤝 Integration

Works with:

• LangChain — Convert to StructuredTool
• CrewAI — Convert to BaseTool
• MCP — Expose via JSON-RPC to Claude / other MCP clients
• Native — Direct SDK usage

📝 License

MIT