Metadata-Version: 2.4
Name: bryter-custom-action-helper
Version: 0.5.0
Summary: CLI for managing and locally testing BRYTER Custom Actions.
License-File: LICENSE
Author: Jonas Bienert
Author-email: bienert@bryter.io
Requires-Python: >=3.11,<4
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: aiohttp (>=3.13.4,<4.0.0)
Requires-Dist: keyring (>=25.6.0,<26.0.0)
Requires-Dist: platformdirs (>=4.3.8,<5.0.0)
Description-Content-Type: text/markdown

# Custom Action Helper

CLI for managing and locally testing BRYTER Custom Actions.

This is a community project and is not officially supported by BRYTER.

![Custom Action Helper CLI help screenshot](docs/cli.png)

## Getting started

### Requirements

- Python 3.11+
- `uv` ([installation guide](https://docs.astral.sh/uv/getting-started/installation/))
- Node.js (only required for `test`)

### Installation (recommended for all OS)

Use `uv tool` on macOS, Linux, and Windows:

```bash
uv tool install custom-action-helper
```

Verify:

```bash
custom-action-helper set
custom-action-helper list
```

Alternative without permanent install:

```bash
uvx custom-action-helper --help
```

### How to use

1. `cd` into your Custom Action project directory.
2. Run a command and pass the application URL as the second positional argument.

Example URL:

```text
https://app.bryter.io/applications/<application-id>/build
```

Examples:

```bash
custom-action-helper list https://app.bryter.io/applications/<application-id>/build
custom-action-helper install https://app.bryter.io/applications/<application-id>/build --implementation-file extract.ts
custom-action-helper update https://app.bryter.io/applications/<application-id>/build --implementation-file extract.ts
custom-action-helper log https://app.bryter.io/applications/<application-id>/build --environment test
custom-action-helper delete https://app.bryter.io/applications/<application-id>/build --action-id <action-id>
```

If values are missing (for example API token), the tool prompts you.
When entering an application URL where a base URL is expected, the tool auto-extracts the application ID.

## Commands

- `list`: show actions for the selected application
- `install`: create action from metadata and upload implementation
- `update`: update action metadata and upload implementation
- `log`: fetch action event logs
- `delete`: permanently delete an action (requires typed confirmation)
- `reset`: force prompts on next run for values not set in the current configuration

`delete` always shows a high-visibility warning and only executes if you type exactly:

```text
delete action
```

## Flags

| Flag | Description |
| --- | --- |
| `--base-url` | API base URL (example: `https://app.bryter.io/api/`) |
| `--api-token` | Securely prompt for API token (does not accept token values) |
| `--api-token-file` | Read API token from a text file |
| `--application-id` | BRYTER application ID |
| `--environment-id` | Environment ID for `op_env_info` |
| `--action-id` | Explicit action ID |
| `--action` | Select an action by value. You can pass action `id`, action `key`, or action `name` (example: `--action extract_pdf`). |
| `--environment` | Environment name for log resolution |
| `--events-path` | Explicit events path for `log` |
| `--metadata-file` | Metadata JSON file (default for install/update: `metadata.json`) |
| `--implementation-file` | Implementation file (`.ts`/`.js`) |
| `--connection-name` | Connection name for `op_create_connection` |
| `--project-path` | Override project directory |
| `--repo-url` | Library repository URL for `lib` commands |
| `--repo-ref` | Library repository ref (branch/tag/commit) |
| `--repo-path` | Local clone path for library repo |
| `--integrations-path` | Integrations directory inside library repo |
| `-y`, `--yes` | Auto-confirm confirmation prompts |
| `--verbose` | Enable verbose logs |

## Configuration

The tool stores your settings automatically and prompts for missing values when needed.

Useful commands:

- `custom-action-helper set`: show current settings
- `custom-action-helper set <key> <value>`: update a setting
- `custom-action-helper set token`: securely enter an API token
- `custom-action-helper reset`: force prompts again on the next run

Common setup:

```bash
custom-action-helper set base_url https://app.bryter.io/api/
custom-action-helper set application_id <application-id>
custom-action-helper set environment_name <environment-name>
custom-action-helper set log_level error
```

## Library functionality (`lib`)

`lib` helps you consume a shared repository of custom action templates/integrations.

Before using `lib`, configure the repository URL once:

```bash
custom-action-helper set custom_actions_repo_url https://gitlab.com/ryter/custom/custom-actions.git
```

- `custom-action-helper lib ls`: list available folders in the library
- `custom-action-helper lib refresh`: sync/refresh the local library cache
- `custom-action-helper lib install <folder>`: use a library folder as project context, then run install flow
- `custom-action-helper lib update <folder>`: use a library folder as project context, then run update flow

## Local test functionality (`test`)

`test` is intended for developers working on implementation code.

It runs your implementation locally using the selected project directory and the project `.env` file.

```bash
node --env-file=.env --import tsx <implementation-file> --local-test
```

## Uninstallation

If installed via `uv tool`:

```bash
uv tool uninstall custom-action-helper
```

If you used repository scripts instead, use the matching uninstall flag:

```bash
./scripts/install.sh --uninstall
./scripts/install.ps1 -Uninstall
```

## Building

```bash
poetry build
```

## Contact

- Jonas Bienert
- bienert@bryter.io

