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
from matimo_bruno import get_tools_path

matimo = await Matimo.init(get_tools_path())

# 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'
})

# Add a request to an existing collection
added = await matimo.execute('bruno_add_request', {
    'collection_path': './collections/new-service',
    'request_name': 'get-users',
    'method': 'GET',
    'url': 'https://api.example.com/users',
})

📋 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. matimo-bruno only calls the bru on your PATH and does not bundle it
• 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