Skip to main content
The bru import command converts API specifications from other formats (OpenAPI, WSDL) into Bruno collections, making it easy to migrate existing API documentation or create collections from API specs.

​
Synopsis

bru import <type> [options]

​
Arguments

​
type
string
required
Type of collection to import. Supported values:
  • openapi - Import from OpenAPI/Swagger specification (JSON or YAML)
  • wsdl - Import from WSDL (Web Services Description Language)

​
Options

​
Source

​
-s, --source
string
required
Path to the source file or URL. Supports:
  • Local file paths (absolute or relative)
  • HTTP/HTTPS URLs
  • For OpenAPI: .json, .yml, or .yaml files
  • For WSDL: .wsdl or .xml files
Examples:
  • --source api.yml
  • --source https://example.com/api-spec.json

​
Output

​
-o, --output
string
Path to the output directory where the Bruno collection will be created.
  • If the path is an existing directory, a new subdirectory will be created using the collection name
  • If the path doesn’t exist, it will be created as the collection directory
  • The parent directory must exist
Conflicts with --output-file.Example: --output ~/Desktop/my-collection
​
-f, --output-file
string
Path to the output JSON file. Instead of creating a Bruno collection directory structure, this exports the collection as a single JSON file.Conflicts with --output.Example: --output-file ~/Desktop/my-collection.json
You must specify either --output or --output-file, but not both.

​
Collection Configuration

​
-n, --collection-name
string
Name for the imported collection. If not specified, the collection name is derived from:
  • The OpenAPI spec’s info.title field
  • The WSDL service name
  • The source filename
Example: --collection-name "My API"
​
--collection-format
string
default:"opencollection"
Format of the imported collection files. Available formats:
  • opencollection - Uses YAML format (.yml files) for the collection structure
  • bru - Uses Bruno’s native .bru format
Example: --collection-format bru

​
OpenAPI-Specific Options

​
-g, --group-by
string
default:"tags"
How to group the imported requests. Only applicable for OpenAPI imports.Available options:
  • tags - Group requests by OpenAPI tags (default)
  • path - Group requests by URL path structure
Example: --group-by path

​
Network & Security

​
--insecure
boolean
default:"false"
Skip SSL certificate verification when fetching from URLs. Useful when importing from servers with self-signed certificates.
Use with caution. Only use this option when importing from trusted sources.
Example: --source https://self-signed.example.com/api.json --insecure

​
Exit Codes

​
0
Success
Import successful - collection created or JSON file written
​
1
Error
Import failed due to one of the following reasons:
  • Unsupported import type
  • Missing required options (source, output, or output-file)
  • Source file or URL not found
  • Failed to parse the specification
  • Invalid specification format
  • Output directory does not exist
  • Output directory is not empty
  • Network error when fetching from URL
  • SSL certificate error

​
Examples

​
OpenAPI Import

​
Basic Import from Local File

Import from a local OpenAPI YAML file: 
bru import openapi --source api.yml --output ~/Desktop/my-collection --collection-name "My API"
Using short aliases: 
bru import openapi -s api.yml -o ~/Desktop/my-collection -n "My API"

​
Import from URL

Import from a remote OpenAPI specification: 
bru import openapi --source https://example.com/api-spec.json --output ~/Desktop --collection-name "Remote API"
Import from URL with self-signed certificate: 
bru import openapi --source https://self-signed.example.com/api.json --insecure --output ~/Desktop

​
Export as JSON

Export the imported collection as a single JSON file: 
bru import openapi --source api.yml --output-file ~/Desktop/my-collection.json --collection-name "My API"
Short form: 
bru import openapi -s api.yml -f ~/Desktop/my-collection.json -n "My API"

​
Grouping Options

Group requests by OpenAPI tags (default): 
bru import openapi --source api.yml --output ~/Desktop/my-collection --group-by tags
Group requests by URL path structure: 
bru import openapi --source api.yml --output ~/Desktop/my-collection --group-by path
Short form: 
bru import openapi -s api.yml -o ~/Desktop/my-collection -g path

​
Collection Format

Import as Bruno native format: 
bru import openapi --source api.yml --output ~/Desktop/my-collection --collection-format bru
Import as OpenCollection format (YAML): 
bru import openapi --source api.yml --output ~/Desktop/my-collection --collection-format opencollection

​
WSDL Import

​
Basic Import from Local File

Import from a local WSDL file: 
bru import wsdl --source service.wsdl --output ~/Desktop/soap-collection --collection-name "SOAP Service"
Short form: 
bru import wsdl -s service.wsdl -o ~/Desktop/soap-collection -n "SOAP Service"

​
Import from URL

Import from a remote WSDL: 
bru import wsdl --source https://example.com/service.wsdl --output ~/Desktop --collection-name "Remote SOAP Service"
Short form: 
bru import wsdl -s https://example.com/service.wsdl -o ~/Desktop -n "Remote SOAP Service"

​
Understanding OpenAPI Grouping

​
Group by Tags (Default)

When using --group-by tags, the importer creates folders based on OpenAPI tags: 
openapi: 3.0.0
paths:
  /users:
    get:
      tags: [Users]
  /products:
    get:
      tags: [Products]
Results in: 
my-collection/
├── Users/
│   └── Get Users.bru
└── Products/
    └── Get Products.bru

​
Group by Path

When using --group-by path, the importer creates folders based on URL structure: 
openapi: 3.0.0
paths:
  /api/v1/users:
    get: ...
  /api/v1/products:
    get: ...
Results in: 
my-collection/
└── api/
    └── v1/
        ├── users/
        │   └── Get Users.bru
        └── products/
            └── Get Products.bru

​
Collection Formats

​
OpenCollection Format (YAML)

The opencollection format uses YAML files: 
my-collection/
├── bruno.yml          # Collection metadata
├── request1.yml       # Request definition
└── folder/
    └── request2.yml

​
Bruno Native Format

The bru format uses Bruno’s native .bru files: 
my-collection/
├── bruno.json         # Collection metadata
├── request1.bru       # Request in .bru format
└── folder/
    └── request2.bru

​
Error Handling

​
Common Errors

Source not found: 
Error: File does not exist: api.yml
Solution: Check the file path or URL. Network errors: 
Error: No response received from server. Check the URL and your network connection.
Solution: Verify the URL is accessible and your network connection is working. SSL certificate errors: 
Error: SSL Certificate error: DEPTH_ZERO_SELF_SIGNED_CERT. Try using --insecure if you trust this source.
Solution: Use the --insecure flag if you trust the source. Invalid specification: 
Error: Failed to parse content as JSON or YAML
Solution: Verify the specification file is valid JSON or YAML. Output directory issues: 
Error: Parent directory does not exist: /invalid/path
Solution: Ensure the parent directory exists before running the import. Directory not empty: 
Error: Output directory is not empty: ~/Desktop/my-collection
Solution: Choose a different output path or clear the existing directory.

​
Network Timeouts

When importing from URLs, the command has a 30-second timeout. If the source is large or the network is slow, the import may fail: 
Error: Request timed out. The server took too long to respond.
In this case, download the specification file locally and import from the file: 
curl -o api.yml https://example.com/api-spec.yml
bru import openapi --source api.yml --output ~/Desktop/my-collection

​
Size Limits

The importer has a maximum content length limit of 10 MB for URL imports. For larger specifications, download the file locally first.

Build docs developers (and LLMs) love

Get started for freeTalk to us