Metadata-Version: 2.4
Name: browsez-cli
Version: 0.1.3
Summary: CLI tool for publishing tools and UI modules to the BrowsEZ platform
Author: Bryan Abraham
License: MIT
Project-URL: Homepage, https://github.com/browsez/cli
Project-URL: Documentation, https://github.com/browsez/cli#readme
Project-URL: Repository, https://github.com/browsez/cli
Keywords: browsez,cli,tools,publishing
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Build Tools
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: types-PyYAML; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# BrowsEZ CLI

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

## Installation

### From PyPI

```bash
pip install browsez-cli
```

### From Source (GitHub)

```bash
# 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

```bash
# 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:

```json
{
  "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:

```bash
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:

```yaml
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

```bash
# 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
