pyboomi-cli 0.4.0
Command-line interface for Boomi Platform API
Requires Python: >=3.8
Keywords: boomi, api, cli, integration, platform, etl, middleware

# pyboomi-cli

Command-line interface for the Boomi Platform API.

## Installation

### For Development

```bash
# Clone the repository
git clone https://github.com/iesoftwaredeveloper/pyboomi-cli
cd pyboomi-cli

# Install with development dependencies
pip install -e .[dev]
```

### For Usage (when published)

```bash
pip install pyboomi-cli
```

### From Source

```bash
git clone https://github.com/iesoftwaredeveloper/pyboomi-cli
cd pyboomi-cli
pip install -e .
```

## Usage

### Authentication

**Recommended: Use environment variables for authentication**

```bash
export BOOMI_ACCT=your-account-id
export BOOMI_USER=your-username
export BOOMI_TOKEN=your-api-token

# Now run commands without authentication flags
boomi folder query
boomi component get 1234-abcd
```

Alternatively, use command-line options (must be specified BEFORE the subcommand):

```bash
# Correct: Options before subcommand
boomi folder --account-id YOUR_ACCOUNT_ID --username YOUR_USERNAME --api-token YOUR_API_TOKEN query

# Incorrect: Options after subcommand will fail
boomi folder query --account-id YOUR_ACCOUNT_ID  # This will NOT work
```

### Examples

```bash
# Get help (both entry points are available)
boomi --help
pyboomi --help

# Query folders (folders alias is supported)
boomi folder query
# or
boomi folders query

# Filter folders by name and print verbose request/response
boomi folder query --name "My Folder" --verbose

# Filter folders with parent constraints
boomi folder query --name "My Folder" --parent-id 0000-parent-id
boomi folder query --name "My Folder" --parent-name "Parent Folder"
boomi folder query --name "My Folder" --parent-path "/Root/Parent"

# Create a folder (parent can be provided by id or name/path)
boomi folder create --name "New Folder" --parent-id 0000-parent-id
boomi folder create --name "New Folder" --parent-name "Parent Folder"
boomi folder create --name "New Folder" --parent-name "Parent Folder" --parent-path "/Root/Parent"

# Get component XML (optionally include branch/version with ~)
boomi component get 1234-abcd
boomi component get 1234-abcd --branch-id 5678-branch --version 1.0

# Get component metadata for a branch (json|yaml|text)
boomi component metadata 1234-abcd --branch-id 5678-branch --output-format json

# Create a packaged component
boomi package create 1234-abcd --version 1.0.0 --notes "Initial package"

# Query packaged components by component ID or version (supports xml)
boomi package query --component-id 1234-abcd --package-version 1.0.0 --output-format xml

# Query branches (filter by name or parent)
boomi branch query --name "feature-x"

# Create a new branch under a parent branch
boomi branch create 1111-parent "feature-x"

# Update a branch
boomi branch update 2222-branch --name "feature-x-renamed" --ready

# Delete a branch
boomi branch delete 2222-branch
```

## Commands

- `folder` — Manage Boomi folders (group command, alias: `folders`)
  - Subcommands:
    - `folder query` — Query and list folders (`--name`, `--parent-id`, `--parent-name`, `--parent-path`, `--verbose`)
    - `folder create` — Create a folder (`--name` required; `--parent-id` or `--parent-name` required, with optional `--parent-path` to disambiguate; `--output-format` `json|yaml|text`)
  - Common options: `--account-id`, `--username`, `--api-token`
- `component` — Manage Boomi components (group command)
  - Subcommands:
    - `component get <component_id>` — Get component XML (`--branch-id`, `--version` optional; always returns XML)
    - `component metadata <component_id>` — Get component metadata (`--branch-id` optional; `--output-format` `json|yaml|text`)
  - Common options: `--account-id`, `--username`, `--api-token`
- `package` — Manage Boomi packages (group command)
  - Subcommands:
    - `package create <component_id> --version <version>` — Create packaged component (`--notes`, `--branch-name`, `--output-format` `json|yaml|text|xml`)
    - `package get <packaged_component_id>` — Get packaged component (`--output-format` `json|yaml|text|xml`)
    - `package query` — Query packaged components (`--component-id`, `--package-version`, `--output-format` `json|yaml|text|xml`)
  - Common options: `--account-id`, `--username`, `--api-token`
- `branch` — Manage Boomi branches (group command)
  - Subcommands:
    - `branch get <branch_id>` — Get a branch
    - `branch query` — Query branches (`--name`, `--parent-branch-id`, `--package-id`, `--ready`, `--output-format` `json|yaml|text`)
    - `branch create <parent_branch_id> <branch_name>` — Create a branch (`--package-id`, `--output-format` `json|yaml|text`)
    - `branch update <branch_id>` — Update a branch (`--name`, `--description`, `--ready/--not-ready`, `--output-format` `json|yaml|text`)
    - `branch delete <branch_id>` — Delete a branch
  - Common options: `--account-id`, `--username`, `--api-token`
- `process` — Manage Boomi processes (alias: `processes`) — placeholder

## Environment Variables

**Recommended: Use environment variables instead of command-line options**

- `BOOMI_ACCT`: Your Boomi account ID
- `BOOMI_USER`: Your Boomi username (email)
- `BOOMI_TOKEN`: Your Boomi API token
- `BOOMI_AUTH`: Base64 encoded Basic Auth string (alternative to username/token)

Environment variables are preferred because:
- More secure (not visible in command history or process lists)
- Cleaner command syntax
- Easier to manage across multiple commands
- Can be set once per session or in shell configuration

If you must use command-line options, remember they must be specified BEFORE the subcommand:
```bash
# Correct
boomi component --account-id ACCT123 get <component-id>

# Incorrect
boomi component get --account-id ACCT123 <component-id>
```

## Output Formats

Many commands support `--output-format` with the following values:

- `json` (default)
- `yaml` (falls back to json if PyYAML is not installed)
- `text` (simple key/value text)
- `xml` (returns raw XML when requested; defaults to XML for `component get`)

## Templates

The `templates/` directory contains XML templates for various Boomi component types including:

- **Processes**: Unit test harnesses and process templates
- **Connectors**: Database, API, and file connectors
- **Profiles**: JSON, XML, flat file, and database profiles
- **Maps**: Data mapping templates and functions
- **APIs**: API services and proxy configurations
- **Scripts**: Process and map scripts
- **Certificates**: Security certificate templates

These templates provide standardized starting points for creating Boomi components. See [TEMPLATE_SYSTEM.md](TEMPLATE_SYSTEM.md) for detailed information about the template system and usage.

## Documentation

- [CHANGELOG.md](CHANGELOG.md) - Version history and release notes
- [TEMPLATE_SYSTEM.md](TEMPLATE_SYSTEM.md) - Template system documentation
- [TEMPLATES_STRUCTURE.md](TEMPLATES_STRUCTURE.md) - Template directory structure