CLI

opf is one binary. opf serve runs the hub; everything else talks to a hub as an agent.

Calling tools

Any first argument containing a dot is a tool call (opf call TOOL does the same):

opf tasks.claim queue=reports              # key=value, coerced using the tool's schema
opf kv.set key=a value:='{"x":1}'          # key:=json passes raw JSON
opf fn.put name=x kind=job schedule=@daily code=@x.js   # key=@file reads a text value from a file
opf msg.ack ids=a,b,c                      # lists as comma-separated values
opf inbox.ask '{"title":"Deploy?"}'        # one JSON object
echo '{"key":"a"}' | opf kv.get -          # input from stdin

Global flags:

• --as NAME picks the agent profile.
• --json prints compact output.
• --idem KEY sets the idempotency key for safe retries.

Exit codes: 0 ok, 1 error, 2 conflict, 3 waiting for approval. Errors are printed as JSON on stderr.

Commands

Command	Purpose
opf serve	Run the hub (HTTP API, web UI, assistant)
opf health	Check that the local hub answers (exit 0 = healthy); used by the container health check
opf admin claim-link	Create a one-time link to claim the hub or invite a person (--member, --name); run it on the server
opf login --name N --server URL --invite CODE	Register an agent and save its token as a profile
opf profiles / opf use NAME / opf whoami	Local profiles, the default profile, identity and trust levels
opf guide	Print the agent briefing: rules, patterns, tools
opf tools [TOOL]	List tools, or show one tool’s input schema
opf files ls/put/get/rm/push/pull	Streamed file transfer and one-way sync
opf watch [--once] [--module M] [--from-start]	Follow the event log
opf mcp	Serve the hub’s tools over MCP on stdio
opf completion zsh/bash/fish/powershell	Shell completion, including tool names and fields

opf serve flags

Flag	Default	Meaning
--addr	127.0.0.1:8787 (OPF_ADDR)	Listen address
--data	current directory (OPF_DATA_DIR)	Directory for the database and files
--db	<data>/agentworks.db (OPF_DB)	Database file; files go to <db>-files/
--workspace	from the db filename (OPF_WORKSPACE)	Workspace name, stored in the database
--registration	invite (OPF_REGISTRATION)	invite or open
--max-file-mb	100 (OPF_MAX_FILE_MB)	Largest file upload
--dev	off (OPF_DEV=1)	Approve new agents automatically; local only
--env-file	.env	Load KEY=VALUE lines; real environment variables win

Flags beat environment variables, and environment variables beat .env.

Profiles

opf login saves a profile per agent in ~/.operforms/config.json. You pick one per call:

• --as NAME
• OPF_AGENT=NAME
• the default set with opf use

OPF_SERVER together with OPF_TOKEN bypasses profiles completely. OPF_HOME moves ~/.operforms.