browsez-cli 0.1.3

CLI tool for publishing tools and UI modules to the BrowsEZ platform

BrowsEZ CLI

A command-line tool for publishing tools and UI modules to the BrowsEZ platform.

Installation

From PyPI

pip install browsez-cli

From Source (GitHub)

# Clone and install in editable mode
cd BrowsEZ-CLI
python -m pip install --upgrade pip setuptools wheel
python -m pip install -e ".[dev]"

Quick Start

# Login to the platform. Local workspaces use password login; Microsoft Entra
# workspaces open the browser and return a saved Platform session to the CLI.
browsez login

# Validate a tool before publishing
browsez validate path/to/tool_directory

# Publish a tool
browsez publish path/to/tool_directory

For Phase 1 AgentCore flows, the expected publish lifecycle is:

1. Create a credential binding in the BrowsEZ Platform Settings UI.
2. Reference that binding from tool.yaml via credential_binding: <binding_slug>.
3. Run browsez publish ....
4. The Platform stores the artifact, creates or updates the Lambda package, and later syncs it to an AgentCore Gateway target when the tool is assigned to an instance.

Commands

Command	Description
browsez login	Login to the BrowsEZ platform; uses password login for local workspaces and browser SSO for Microsoft Entra workspaces
browsez logout	Clear the current session
browsez validate <dir>	Validate a tool without uploading
browsez publish <dir>	Publish a tool to the backend
browsez publish-ui <dir>	Publish a UI module (coming soon)
browsez config show	Show current configuration
browsez config set <key> <value>	Set a config value

Configuration

The CLI uses a .toolrc.json file for configuration. It is auto-created on first run:

{
  "api_base_url": "https://browsez-platform-backend-production.up.railway.app",
  "tenant_id": "sample-tenant-123",
  "default_risk_level": "MEDIUM",
  "upload_timeout": 300,
  "retry_attempts": 3
}

tenant_id is now a legacy compatibility field. Current publish requests are scoped from the authenticated platform session instead of sending an explicit tenant identifier.

Login Behavior

browsez login first asks for the workspace slug and checks that workspace's login mode:

• Local workspaces keep the existing username/password prompt.
• Microsoft Entra workspaces ask for confirmation, open the browser for Microsoft sign-in, listen on a localhost callback, and exchange a one-time code for a normal BrowsEZ session_id.
• The saved .toolrc.json session format is unchanged. browsez publish continues to authenticate with the stored Platform session.
• If the workspace setup is incomplete or Entra OIDC is not configured, the CLI fails before opening the browser.

Override settings via CLI:

browsez config set api-url https://api.example.com
browsez config set risk-level HIGH

Tool Directory Structure

A valid tool directory must have:

tool_name/
├── tool.yaml           # Metadata (name, inputs, outputs)
├── requirements.txt    # Python dependencies
└── src/
    ├── __init__.py
    └── main.py         # Entry point (run function, Input/Output classes)

Example tool.yaml with a credential binding:

name: order_lookup
description: |
  Look up customer orders and return the authoritative order status, line items,
  and fulfillment details from the source system.
inputs:
  type: object
  properties:
    order_id:
      type: string
outputs:
  type: object
  properties:
    result:
      type: object
credential_binding: billing_api

If credential_binding is set, the Platform will resolve that binding and inject the resulting credential environment into the Lambda package used by AgentCore. The Platform preserves the full description for the model-facing tool definition and derives any shorter AgentCore Gateway metadata automatically during assignment.

Development

# Install with dev dependencies
python -m pip install --upgrade pip setuptools wheel
python -m pip install -e ".[dev]"

# Build the package
python -m build

# Upload to PyPI (requires twine and credentials)
twine upload dist/*

Features

• Strict Schema Validation: Ensures tools meet all requirements before packaging
• Deterministic Packaging: Creates consistent zip files with content-based hashing (SHA-256)
• Secure Uploads: Uses pre-signed S3 URLs for artifacts
• Credential Binding Aware: Carries credential_binding from tool.yaml through tool registration
• Lambda-backed Custom Tools: Published custom tools are packaged for BrowsEZ-managed Lambda execution in the AgentCore flow
• Configurable: Supports configuration via file, CLI arguments, and defaults
• Resilient: Implements retry logic and exponential backoff for network operations