Metadata-Version: 2.5
Name: procesio-cli
Version: 0.1.1
Summary: Command-line tooling and an AI agent for the PROCESIO automation platform: drive processes, forms, documents and custom actions from a terminal or from an AI coding assistant.
Project-URL: Homepage, https://procesio.com
Project-URL: Documentation, https://docs.procesio.com
Project-URL: Repository, https://github.com/Procesio-Externals/procesio-cli
Project-URL: Issues, https://github.com/Procesio-Externals/procesio-cli/issues
Project-URL: Changelog, https://github.com/Procesio-Externals/procesio-cli/blob/main/CHANGELOG.md
Author: Ringhel TEAM SRL (PROCESIO)
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agent,automation,cli,ipaas,low-code,mcp,procesio,workflow
Classifier: Development Status :: 4 - Beta
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Requires-Dist: cryptography>=42.0
Requires-Dist: jsonschema>=4.20
Requires-Dist: keyring>=24.0
Requires-Dist: pydantic>=2.5
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31
Provides-Extra: browser
Requires-Dist: beautifulsoup4>=4.12; extra == 'browser'
Requires-Dist: lxml>=5.0; extra == 'browser'
Requires-Dist: playwright>=1.60.0; extra == 'browser'
Requires-Dist: pymupdf>=1.24; extra == 'browser'
Requires-Dist: pypdf>=6.15.0; extra == 'browser'
Provides-Extra: databases
Requires-Dist: pymysql>=1.1; extra == 'databases'
Requires-Dist: pyodbc>=5.1; extra == 'databases'
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1; extra == 'excel'
Description-Content-Type: text/markdown

# PROCESIO CLI + Agent

<!-- mcp-name: io.github.Procesio-Externals/procesio-cli -->

Command-line tooling and an AI agent for the PROCESIO automation platform: drive processes, forms, documents and custom actions from a terminal or from an AI coding assistant.

Everything here talks to a PROCESIO installation over its public API. You point it at
your workspace, store your credentials in your operating system's own secret store,
and drive processes, forms, documents and custom actions from a terminal, a script, or
an AI coding assistant.

- The platform this talks to, where your workspaces live: https://procesio.app
- API and platform documentation: https://docs.procesio.com
- About PROCESIO: https://procesio.com

## Install

Requires Python 3.11. [uv](https://docs.astral.sh/uv/) is the quickest
route, but a plain virtualenv works the same way.

```bash
git clone https://github.com/Procesio-Externals/procesio-cli.git
cd procesio-cli
uv sync
```

The base install is six packages. Everything heavier is an optional extra, pulled
in only if you use the tool that needs it:

```bash
uv sync --extra browser      # real-browser form testing (then: uv run playwright install chromium)
uv sync --extra excel        # reading .xlsx workbooks
uv sync --extra databases    # SQL Server / MySQL queries (pyodbc also needs an ODBC driver)
uv sync --all-extras         # everything
```

## Connect it to your workspace

Credentials never live in a file in this repo. They go into your machine's own store:
Windows Credential Manager, the macOS login Keychain, or the Linux desktop keyring,
all under the name `agents-and-tools:procesio:<secret>`.

PROCESIO accepts two ways of authenticating, and they are not equivalent. Store either
one as a named profile:

```bash
# Your user account. Carries everything that account can do.
python scripts/run-tool.py procesio add-credential --name account --type userpass     --username you@example.com --make-default

# An API key, scoped to one workspace.
python scripts/run-tool.py procesio add-credential --name qa --type apikey     --workspace-id <workspace-guid>

python scripts/run-tool.py procesio check-auth
```

Omit `--password`, `--key` or `--value` and you are prompted without echoing, so the
secret never reaches your shell history or a process listing. Add
`--environment <Client>-<ENV>` to bind a profile to a specific installation.

### Which one to use

| | User and password | API key |
|---|---|---|
| Reaches | everything the account can reach, across workspaces | one workspace |
| Needs a workspace GUID | no | yes, its own, and no other will do |
| Good for | day-to-day building, anything that spans workspaces | CI, a script pinned to one environment, sharing narrow access |

The scoping is enforced by the platform, not by this tool. A workspace-scoped key sends
three headers: the key name, the key value, and `workspaceid`. Send it without that
header and the call is a `401`; send it with a **different** workspace's GUID and it is
also a `401`. So an api-key profile has to be stored with its `workspace_id` to
authenticate at all. `python scripts/run-tool.py procesio list-workspaces` gives you the
GUID.

The practical consequence is worth knowing before you pick. A user profile reaches
endpoints an API key cannot: listing a master workspace's sub-workspaces, for example,
answers `401` for a key and `200` for a user. Prefer the user account while you are
building, and reach for a key when you deliberately want to pin something to a single
workspace.

On a headless machine there is no OS keyring to write to. Pick a store explicitly:

```bash
export AAT_CREDS_BACKEND=encrypted-file
export AAT_SECRETS_PASSPHRASE='...'      # or you will be prompted on a terminal
python scripts/set-credential.py procesio username
```

`AAT_CREDS_BACKEND=file` and `=env` read secrets your host or cluster already manages
(a mounted Kubernetes Secret, or one JSON blob) and are read-only by design, so a
container can never pretend to own the store it reads from.

## First commands

```bash
python scripts/list-tools.py                       # what is installed, and is it ready
python scripts/run-tool.py procesio --help         # every action, with its arguments
python scripts/run-tool.py procesio list-processes
python scripts/run-tool.py procesio run-process --id <process-id> --payload '{}'
```

Every tool prints exactly one JSON object on stdout and nothing else, so you can pipe
it straight into `jq` or into another script. Progress and warnings go to stderr.
Failures print `{"error": {"code", "message", "details"}}` and exit non-zero.

## Using it from an AI assistant

This repo is built to be discovered rather than memorised, which is what makes it
usable by an assistant that has never seen it before.

- `CLAUDE.md` carries a generated **capability router**: a compact map from "what the
  user asked for" to the exact command that does it. It is regenerated from the
  manifests with `python scripts/build-router.py`, so it cannot drift from the code.
- `tools/procesio/SKILL.md` is the tool's full manual, also generated from its
  manifest. An assistant reads it instead of guessing at `--help` output.
- `python scripts/list-tools.py` returns the same information as JSON, including which
  credentials are missing, so an assistant can tell "not installed" from "not
  configured yet".

Point your assistant at the repo root and let it run `scripts/run-tool.py`. Nothing
else is required.

### Or install it into Claude Code as a plugin

One command, and Claude Code carries the tools, the MCP server and the Agent Skills
together. No clone, no path to write into a config file.

```
/plugin marketplace add Procesio-Externals/procesio-cli
/plugin install procesio@procesio-cli
```

The plugin is the `plugin/` folder: the MCP server configuration, four skills and an
icon. It launches the exact PyPI release of this package through `uvx`, so
[uv](https://docs.astral.sh/uv/) has to be on the machine; everything else it resolves
itself on first run. Authenticate with `add-credential` below, run as
`uvx --from procesio-cli procesio add-credential ...` when there is no clone.

**What gets installed is pinned.** The plugin names one exact release and passes
`constraints.txt` and `build-constraints.txt` to `uvx`, so a fresh launch installs exactly the versions that
were resolved and checked for this release, not whatever is newest on PyPI that day. The
pins are checked to have prebuilt wheels for Python 3.11 to 3.14 on Windows, Linux
(x86-64 and ARM) and Apple Silicon. Intel Macs are not covered: `cryptography` no longer
publishes wheels for them, so installing there needs a Rust toolchain.

**On Windows with Smart App Control.** Windows 11 can refuse to load a Python file
whose publisher it cannot confirm, and shows "Part of this app has been blocked" for
each one. The Python builds uv downloads for itself are not signed, so the plugin asks
uv for a Python that is already installed first (`--python-preference system`, never
older than 3.11) and uses uv's own build only when there is none. If
you see those notifications, install Python 3.11 or newer from
[python.org](https://www.python.org/downloads/windows/) (for example
`winget install Python.Python.3.12`), whose files are signed, then restart Claude Code.
Do not ignore them: when the refused file is Python's networking module, no tool call
can reach PROCESIO.

**You can check the tool list you were given.** The MCP server's published tools are
fixed per release, and `server.json` records their digest under
`_meta` > `io.modelcontextprotocol.registry/publisher-provided` > `com.procesio/toolsDigest`.
That file cannot be changed once a version is in the MCP Registry. Hash the `tools` array
a `tools/list` call returns and compare:

```python
import hashlib, json
raw = json.dumps(tools, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
print("sha256:" + hashlib.sha256(raw.encode("utf-8")).hexdigest())
```

A mismatch means the server is not offering what was published for that version. The
server also reports its digest in `server/discover`, but treat that only as a label: a
server cannot vouch for itself.

### Or connect it over MCP, with no shell at all

There are two MCP servers in `webplatform/aat_mcp/`, over the same substrate, for two
different jobs. Both speak JSON-RPC over stdio.

| | `procesio-mcp-chat` | `procesio-mcp` |
|---|---|---|
| tools | 21, one per operation | 6, generic |
| picks up a tool you add | no, it is a declared list | yes, immediately |
| what it is for | a chat client, where each tool has to say what it does | driving the whole registry |
| launched by | the plugin, via `.mcp.json` | your own client config |

**From the MCP Registry, or as a one-click bundle.** The chat server is listed in the
official MCP Registry as `io.github.Procesio-Externals/procesio-cli`, and each release attaches
`procesio-mcp-<version>.mcpb` to its
[GitHub release](https://github.com/Procesio-Externals/procesio-cli/releases). Open that file in
Claude Desktop to install it; the host fetches the Python dependencies with uv. Both are
produced by the tag-driven `release` workflow, which fills in the bundle's hash and
publishes `server.json`, so nothing in the registry is edited by hand.

The curated surface is grouped by what you are building — processes, forms, connectors —
and nothing in it takes a caller-supplied action, so every tool in the list is legible to
a person reading it and to a model choosing between them. Its contents are declared in
`webplatform/aat_mcp/chat_surface.yaml`, and CI checks that every operation it names still
exists with the arguments it claims.

The generic surface is the one to reach for when you want reach rather than a short list.
It exposes the whole registry through six tools rather than one per action:

| tool | what it does |
|---|---|
| `capabilities` | list tools, agents and skills, or one capability's full argument schema |
| `run_tool` | run a tool with structured JSON arguments |
| `run_agent` | run an agent |
| `run_tool_confirmed`, `run_agent_confirmed` | the same, including irreversible actions |
| `get_skill` | fetch a skill's markdown |

Because it reads the registry, a tool you add next to `tools/procesio/` appears in
your assistant immediately, with its argument schema, and you write no integration
code for it.

Point your MCP client at the server with an absolute path to this checkout's Python:

```json
{
  "mcpServers": {
    "procesio": {
      "command": "/abs/path/to/procesio-cli/.venv/bin/python",
      "args": ["/abs/path/to/procesio-cli/webplatform/aat_mcp/server.py"]
    }
  }
}
```

On Windows the interpreter is `.venv\Scripts\python.exe`. The key name differs per
client (`mcpServers` for Claude Desktop and Cursor, `mcp` with `"type": "local"` for
opencode), but the command and args are the same everywhere. For a container there is
also an HTTP transport: `python webplatform/aat_mcp/http_server.py --host 0.0.0.0
--port 8901 --token <secret>`, which requires `Authorization: Bearer <secret>` on
every request. Do not bind it off loopback without a token.

**About the safety gate.** `run_tool` refuses an action the reversibility check calls
irreversible and returns `approval_required`, naming the `*_confirmed` path. MCP
clients mark those as ask, so a person approves each side effect and a model cannot
bypass the gate by picking the plain tool. Know what the check is: it matches English
verbs in the action name and arguments. An action whose name carries no verb it knows
comes back reversible, so silence is absence of evidence rather than a guarantee.
Treat it as a guard rail against obvious mistakes, not as a sandbox, and add verbs to
`agents/_lib/reversibility.py` when you find a gap. Set `AAT_MCP_DENY_IRREVERSIBLE`
for a headless run where even confirmed actions must be refused.

## The rules that are not obvious

Before you build anything, read
[`tools/procesio/PROCESIO-USAGE-GUIDE.md`](tools/procesio/PROCESIO-USAGE-GUIDE.md). It
indexes the platform behaviours that read as failures until you know them, and they all
share a shape: the call succeeds, the status says finished, nothing is logged, and the
thing you asked for did not happen. There is no error to search for, so you look in the
wrong place.

A few of them, so you can judge whether it is worth your time: `<%N%>` in a Node pastes
the value into the source rather than binding it, so a string becomes a subtraction; the
Python action returns only what the script PRINTS, so an assignment returns empty; and an
empty form control bound to a typed variable kills the launch with nothing on screen at
all.

The guide is generated from the tool's own notes, carries the rule and a link, and the
reasoning stays in the note. One copy of every fact.

## The agent

Beyond the raw API tool there is a build-and-test agent that carries the method rather
than the mechanics: how to build a process properly, how to verify it against a live
run, and which smells to look for in someone else's flow.

```bash
python scripts/run-agent.py procesio guidance          # the playbook and best practices
python scripts/run-agent.py procesio checklist         # the self-test discipline
python scripts/run-agent.py procesio verify --process-id <id>
python scripts/run-agent.py procesio audit --process-id <id>
```

`verify` is the one worth wiring into CI: it validates the process, compares what the
designer shows against what the runtime does, launches it and reads the instance
status back.

## Set up in a browser instead

If you would rather not touch a terminal for setup, there is a local console:

```bash
python dashboard/serve.py
```

It binds to loopback only and opens a page that lists every tool, agent and skill
from the live registry. From there you can store credentials straight into your OS
credential store (they never touch a file), edit schema-validated config, see which
tools are ready and which are missing a secret, and run a tool to check it works.
Nothing you enter leaves your machine.

## Build a connector from API documentation

Custom actions are the platform's main extension point: they are how a process calls an
API that PROCESIO does not already speak. `connector-builder` turns API documentation
into a compiled custom action, so the route from a third-party API to something a
process can call is a build rather than a C# project.

The builder is a hosted service at
[connector-builder.procesio.app](https://connector-builder.procesio.app/). Anyone can
create an account there; you do not need anything from us first. Two things to know
before you start:

- **You bring your own LLM key.** The build pipeline runs on a model, and it runs on
  *your* provider account rather than ours. Set it once, in the builder, or from here.
- **You authenticate either with an `acb_` API key or with the account's email and
  password.** The key is long-lived and simplest for a script; the login mints a JWT.

```bash
python scripts/set-credential.py connector-builder api-key      # acb_...
# or: set-credential.py connector-builder username / password

python scripts/run-tool.py connector-builder set-llm-key --provider anthropic --api-key sk-ant-...
python scripts/run-tool.py connector-builder create-build --api-url <docs-url>     --user-requirements "what the connector should do"
```

From there the agent drives the loop rather than you memorising the stages:

```bash
python scripts/run-agent.py connector-builder next-step --build-id <id>
```

It answers the builder's clarifying questions, approves the plan, generates, compiles,
and hands back the `.nupkg` to upload to your workspace.

## Test the form you just built

Building a form is half the job. The agent's playbook is blunt about the other half:
a form is not done until every tab, every control and every event has been exercised
live and the runtime diagnostics are clean. Screenshots hide JS errors, failed
launches and flicker.

```bash
python scripts/run-tool.py web save-session --name mine --url https://forms.procesio.app
python scripts/run-tool.py web run --session mine --url <form-url> --steps @steps.json
```

The result carries a `diagnostics` block: console output, page errors, failed
requests and bad responses. Any page error, any console error, or any 4xx or 5xx on
the form's own calls means it is not done.

## What is in here

Seven tools, two agents, two skills, and two components that are neither. The
registry is the authority on all of it: `python scripts/list-tools.py` prints what is
installed, how many actions each one exposes, and which credentials are still
missing. The counts below come from that listing.

### Tools

Run any of them with `python scripts/run-tool.py <tool> <action> [options]`. An
action is required; `--help` lists the actions a tool exposes.

| Tool | Actions | What it does |
|---|--:|---|
| `procesio` | 442 | The platform API: processes, forms, documents, custom actions, environments, credentials, schedules. |
| `connector-builder` | 55 | Turns API documentation into a compiled PROCESIO custom action. Custom actions are the platform's main extension point, so this is the shortest route from a third-party API to something a process can call. |
| `mysql` | 9 | Query the MySQL database a SQL action talks to, to see what a process actually wrote. |
| `sqlserver` | 9 | The same, for SQL Server. |
| `web` | 9 | Drive a real browser: render, click, fill, screenshot, read runtime diagnostics. |
| `xlsx` | 3 | Read a workbook outside a process. PROCESIO's Node allowlist ships no xlsx library. |
| `framework-map` | 2 | Render everything installed as one bilingual page: `python scripts/run-tool.py framework-map build`. |

### Agents

An agent carries method rather than mechanics. Run one with
`python scripts/run-agent.py <agent> <action>`.

| Agent | Actions | What it does |
|---|--:|---|
| `procesio` | 5 | Build and test: the playbook, the self-test checklist, a verify gate against a live process, and a static audit for inefficiency and robustness smells. |
| `connector-builder` | 4 | Drives the connector loop end to end: gather, plan, generate, compile, improve from the feedback. |

### Skills

Knowledge an AI assistant loads on its own from the description; there is nothing to
run. `python scripts/get-skill.py <name> --content` prints one.

| Skill | What it covers |
|---|---|
| `procesio-platform-advisor` | Platform knowledge: capabilities, use cases, feasibility evaluation, implementation practice. |
| `sql-server-optimizer` | Reviews the T-SQL a process runs. Inlining flow variables into SQL text is both injection-prone and the wrong action configuration, and this is what catches it. |

### Two components that are not tools

`dashboard/` is the setup console, started with `python dashboard/serve.py`. It is not
in the registry and does not run through `run-tool.py`.

`webplatform/aat_mcp/` is the MCP server, started by your MCP client rather than by
you. See the section above.

## Layout

```
tools/procesio/      the API client, DTOs, flow model, layout engine, handlers
agents/procesio/     the build-and-test agent and its doctrine
tools/_lib/          credentials, JSON I/O contract, manifest loading
skills/              knowledge your assistant loads on its own
dashboard/           the local setup console
scripts/             run-tool, run-agent, list-tools, set-credential, build-router
registry.py          manifest discovery; nothing has a hardcoded tool list
```

A tool is a directory with a `tool.yaml` manifest, an entrypoint, and a README. The
manifest is the contract: the registry reads manifests, and everything else reads the
registry. If you add a tool of your own next to `tools/procesio/`, it shows up in
`list-tools.py` and in the router without registering it anywhere.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for how to open an issue or a pull request, and
for the two rules that come from how this repository is built: don't move files, and
never commit a `.procesio` export. Short version of the mechanics: this repo is
generated from an internal monorepo, so a merged change is copied upstream and comes
back on the next publish. That is invisible to you as a contributor, but it explains
why commits here arrive in batches.

For a security problem, don't open an issue. See [SECURITY.md](SECURITY.md).

## License

Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
