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. 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 [email protected] --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

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 <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 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==<that release>. 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-<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.