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

PROCESIO accepts two ways of authenticating, and they are not equivalent. Store either one as a named profile. An API key is created in the PROCESIO web app and has two parts you will both need: a name/handle (its label) and a secret value (the long token) - copy each when you create it. A user account is simply your PROCESIO login.

# 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

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

For an API key, --key is the key's name/handle and --value is its secret token, and both come from the PROCESIO UI. 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 - 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 --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 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 carries a small runtime project in plugin/: pyproject.toml names one release of procesio-cli and uv.lock pins it and every dependency to exact versions with hashes, and the server starts as uvx procesio-cli== . An install that honours the lock gets exactly what was locked for this release, not whatever is newest on PyPI that day. A clone can do the same with constraints.txt and build-constraints.txt, which pin every package to versions with 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 (UV_PYTHON_PREFERENCE=system in its environment, 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- .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 , which requires Authorization: Bearer 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 th