Metadata-Version: 2.4
Name: pyboomi-cli
Version: 0.14.0
Summary: Command-line interface for Boomi Platform API
Author-email: Robert Little <robert@iesoftwaredeveloper.com>
Maintainer-email: Robert Little <robert@iesoftwaredeveloper.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/iesoftwaredeveloper/pyboomi-cli
Project-URL: Documentation, https://github.com/iesoftwaredeveloper/pyboomi-cli#readme
Project-URL: Repository, https://github.com/iesoftwaredeveloper/pyboomi-cli.git
Project-URL: Bug Tracker, https://github.com/iesoftwaredeveloper/pyboomi-cli/issues
Project-URL: Changelog, https://github.com/iesoftwaredeveloper/pyboomi-cli/blob/main/CHANGELOG.md
Keywords: boomi,api,cli,integration,platform,etl,middleware
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyboomi_platform>=0.2.3
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: tox>=4.0.0; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Provides-Extra: lint
Requires-Dist: black>=23.0.0; extra == "lint"
Requires-Dist: flake8>=6.0.0; extra == "lint"
Requires-Dist: mypy>=1.0.0; extra == "lint"
Requires-Dist: isort>=5.12.0; extra == "lint"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.19.0; extra == "docs"
Dynamic: license-file

# pyboomi-cli

Command-line interface for the Boomi Platform API.

## Disclaimer

**This is an independent, unofficial project.** It is not affiliated with, endorsed by, or supported by Boomi or any related entities. This tool is provided as-is for personal and community use. For official Boomi tools and support, visit [boomi.com](https://boomi.com).

## Installation

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

## 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 by id or name (optional branch/version; --save writes XML to file)
boomi component get 1234-abcd
boomi component get --name "My Process" --branch-name main
boomi component get 1234-abcd --branch-id 5678-branch --version 1.0 --save

# Get or query component metadata (json|yaml|text|xml); query by folder without positional id
boomi component metadata 1234-abcd --branch-id 5678-branch --output-format json
boomi component metadata --folder-name "Integrations" --type process

# Component references (where-used)
boomi component references get 1234-abcd
boomi component references query --component-id 1234-abcd

# Create from template, diff two versions, update from file or stdin
boomi component create --template processes/basic.xml --folder-id <folder-id>
boomi component diff 1234-abcd 1 2 --output-format json
boomi component update 1234-abcd --component-file ./component.xml

# Environments (alias: environments)
boomi environment query --name "Production"
boomi environment get --name "Production"
boomi environment extensions get <environment-uuid>
boomi environment extensions query --environment-id <environment-uuid>

# Deployed packages — deploy, list, remove (alias: deployment)
boomi deployed create --environment-id <env-id> --package-id <package-id>
boomi deployed query --environment "Production" --active

# Runtime management (alias: runtime-mgmt); nested groups — use --help to explore
boomi runtime --help
boomi runtime atom get <atom-id>
boomi runtime cloud query

# 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

# Create a merge request
boomi merge create --source-branch-id QjoyMDI1OTk --destination-branch-id QjoyMDI1OTg --strategy OVERRIDE --priority-branch SOURCE

# Get merge request details
boomi merge get TVI6NTB9

# Query merge requests by branch
boomi merge query --source-branch-id QjoyMDI1OTk --stage MERGED

# Execute a merge
boomi merge execute TVI6NTQ5 --action MERGE

# Update merge request to resolve conflicts
boomi merge update TVI6NjY3 --component-guid 50e9d4f5-fea6-4ab0-91b1-d8b683ede8c0 --resolution KEEP_DESTINATION

# Delete a merge request
boomi merge delete TVI6NTQ5
```

## 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|xml`)
  - Common options: `--account-id`, `--username`, `--api-token`
- `component` — Manage Boomi components (group command)
  - Subcommands:
    - `component get [component_id]` — Get component XML (positional id optional if `--name` is set). Options: `--name`, `--branch-id`, `--branch-name`, `--version`, `--deleted`, `--save`, `--save-file`, `--quiet`. Output is XML.
    - `component metadata [component_id]` — Metadata for one component or **query mode** (no id): provide `--folder-id` and/or `--folder-name`, with optional `--name`, `--branch-id`, `--branch-name`, `--version`, `--type`, `--sub-type`, `--current-version`, `--deleted`, `--output-format`, `--save`, `--save-file`, `--quiet`.
    - `component references` — Where-used: `references get`, `references bulk`, `references query`, `references query-more` (see `boomi component references --help`).
    - `component create` — Create from `--template` (and `--folder-id`, branch options, `--parameter key=value`, `--no-prompt`, etc.); see [TEMPLATE_SYSTEM.md](TEMPLATE_SYSTEM.md).
    - `component diff <component_id> <source_version> <target_version>` — Compare versions (`--output-format` `json|yaml|text|xml`, `--save`, `--quiet`).
    - `component update <component_id>` — Update from stdin or `--component-file` (`--output-format`, `--verbose`, `--save`, `--quiet`).
  - 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|xml`)
    - `branch create <parent_branch_id> <branch_name>` — Create a branch (`--package-id`, `--output-format` `json|yaml|text|xml`)
    - `branch update <branch_id>` — Update a branch (`--name`, `--description`, `--ready/--not-ready`, `--output-format` `json|yaml|text|xml`)
    - `branch delete <branch_id>` — Delete a branch
  - Common options: `--account-id`, `--username`, `--api-token`
- `merge` — Manage Boomi merge requests (group command)
  - Subcommands:
    - `merge create` — Create a merge request (`--source-branch-id`, `--destination-branch-id`, `--strategy`, `--priority-branch`, `--note`, `--output-format`, `--save`, `--save-file`, `--quiet`)
    - `merge get <merge_request_id>` — Get a merge request by ID (`--output-format`, `--save`, `--quiet`, …)
    - `merge bulk <merge_request_id>...` — Retrieve multiple merge requests by IDs
    - `merge query` — Query merge requests (`--source-branch-id`, `--destination-branch-id`, `--stage`, `--created-by`, `--modified-by`, `--created-date`, `--modified-date`, `--output-format`, …)
    - `merge update <merge_request_id>` — Update a merge request (`--strategy`, `--note`, `--component-guid`, `--resolution`, `--exclude-component`, `--output-format`, …)
    - `merge execute <merge_request_id>` — Execute a merge action (`--action` `MERGE|REVERT|RETRY_DRAFTING`, `--output-format`, …)
    - `merge delete <merge_request_id>` — Delete a merge request (`--auto-approve`, `--save`, `--quiet`, …)
  - Common options: `--account-id`, `--username`, `--api-token`
- `environment` — Boomi environments (alias: `environments`)
  - Subcommands:
    - `environment query` / `environment q` — Query (`--name`, `--classification`, `--id`, `--output-format`, `--save`, `--save-file`, `--quiet`)
    - `environment get` — Get by id or `--name` (same output/save options)
    - `environment extensions` — EnvironmentExtensions API via `client.environment`: `extensions get`, `query`, `query-more`, `bulk`, `update` (see `boomi environment extensions --help`)
  - Common options: `--account-id`, `--username`, `--api-token`
- `deployed` — Deployed packages / deployments (alias: `deployment`)
  - Subcommands: `deployed create`, `get`, `delete`, `bulk`, `query`, `query-more` (see [docs/commands.rst](docs/commands.rst) or `boomi deployed --help` for options including `--environment`, date filters, `--output-format` `json|yaml|text|xml`)
  - Common options: `--account-id`, `--username`, `--api-token`
- `runtime` — Boomi Runtime Management API (alias: `runtime-mgmt`). Nested groups include `atom`, `cloud`, `shared-web-server`, `shared-server-information`, `restart-request`, `release-schedule`, `runtime-properties`, `observability-settings`, `node-offboard`, `move-queue-request`, `list-queues`, `java-upgrade`, `java-rollback`, `installer-token`, `deployed-expired-certificate`, `clear-queue`, `atom-disk-space`. Use `boomi runtime <group> --help` for subcommands and flags.
  - 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`)

Many commands also support `--save`, `--save-file`, and `--quiet` to write output to a file and/or suppress stdout.

## 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
- [docs/](docs/) — Sphinx source (`*.rst`); build HTML with `cd docs && pip install -e .[docs] && make html` (see [docs/README.md](docs/README.md))
- [TEMPLATE_SYSTEM.md](TEMPLATE_SYSTEM.md) — Template system documentation
- [TEMPLATES_STRUCTURE.md](TEMPLATES_STRUCTURE.md) — Template directory structure
- [CONTRIBUTING.md](CONTRIBUTING.md) — Development and contribution guidelines
