PROCESIO

PROCESIO CLI + Agent

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 is the quickest route, but a plain virtualenv works the same way.

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:

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:

# 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

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:

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

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 launches the MCP server through uvx, so uv has to be on the machine; everything else it needs it resolves itself on first run. Authenticate exactly as a clone does, with add-credential below.

What gets installed is pinned. The plugin 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 (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:

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.

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. 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:

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:

{
  "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. 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.

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:

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. 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.

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:

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.

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.

Agents

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

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.

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 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.

License

Apache-2.0. See LICENSE and NOTICE.