CLI guide

The Picoo CLI is organized around tasks. Start with picoo --help, or add --help after any command to see the options installed on your machine.

Check your setup

picoo doctor

This checks whether the runtimes used by operations, such as Python through uv and Node, are available.

Find an operation

Search by describing the result you want:

picoo search "turn a Markdown file into HTML"

Picoo combines text and semantic matching by default. The result includes an operation ID and enough information to build a run command.

picoo search "create an issue" --top 10
picoo search "create an issue" --mode text
picoo search "create an issue" --json

Use hybrid, semantic, or text for --mode. Use --json when another program will read the results.

To see what is already installed:

picoo list
picoo show picoo/github/create-issue

show prints the operation contract, including its inputs, outputs, runtime, version, and declared permissions.

Run an operation

Pass each input as key=value:

picoo run picoo/github/create-issue \
  --input repo=picoo-dev/picoo \
  --input title="Fix login"

Values are converted to the types declared by the operation. Quote values that contain spaces. Repeat --input for more fields.

Useful run controls:

# Require a specific version
picoo run picoo/github/create-issue --version 1.2.0 --input repo=picoo-dev/picoo --input title="Fix login"

# Never connect to a registry
picoo run picoo/github/create-issue --offline --input repo=picoo-dev/picoo --input title="Fix login"

# Enforce declared access with the operating system sandbox
picoo run picoo/github/create-issue --sandbox --input repo=picoo-dev/picoo --input title="Fix login"

If an operation is missing and you are online, Picoo can fetch it from the configured Registry. --offline changes this to a local-only run.

Create and update operations

Create an operation by giving it an ID, runtime, description, and contract:

picoo create alice/demo/greet \
  --runtime python \
  --description "Return a greeting" \
  --input name:string \
  --output greeting:string

Supported runtimes are python, node, and binary. Inputs and outputs can be repeated. Add ? to an optional input, such as limit:integer?.

You can also declare:

• --entry for a custom entry file.
• --version for the first semantic version. The default is 0.1.0.
• --network for each host the operation may contact.
• --auth and --secret-env for credentials supplied at run time.
• --environment for each non-secret environment variable it may read.
• --python for a Python version requirement such as >=3.12.

Update the contract without recreating the operation:

picoo update alice/demo/greet --version 0.2.0 --description "Return a friendly greeting"

When update receives input, output, network, environment, or secret environment flags, the supplied group replaces that whole group. Include the existing values you want to keep.

See Create your first operation for a complete walkthrough.

Run a workflow

A workflow connects several operations in a TOML file. Validate it before any work is performed:

picoo workflow validate publish.toml
picoo workflow run publish.toml --input title="Hello" --input body="Draft text"

The same command can one-shot a workflow from the configured Registry. Pinning the version makes the workflow definition and dependency lock repeatable:

picoo workflow run alice/workflows/publish \
  --version 1.0.0 \
  --input title="Hello" \
  --input body="Draft text"

Use picoo workflow pull alice/workflows/publish --version 1.0.0 to install without running, then add --offline to require only installed artifacts.

Workflow inputs use ${input.name}. A later step can use a previous result with ${steps.step-id.result.field}. Workflows can define retries, timeouts, and rollback steps in the file.

For staged work, pause after a number of successful steps:

picoo workflow run publish.toml --input title="Hello" --pause-after 1

Picoo prints a run ID. Resume from its saved checkpoint:

picoo workflow resume publish.toml --run-id RUN_ID

Let an MCP client use Picoo operations

Picoo can expose approved operations over a local, standard-input MCP connection:

picoo mcp serve \
  --allow-op picoo/github/create-issue \
  --allow-network api.github.com \
  --allow-auth github \
  --require-sandbox

Repeat the allow flags when more than one value is needed. Omit --allow-op to expose every operation allowed by the other policy settings. Use --require-sandbox when the server must expose nothing unless sandboxing works.

Open the local dashboard

picoo dashboard

The dashboard listens on 127.0.0.1:7331 by default. To use another local port:

picoo dashboard --host 127.0.0.1 --port 7440

Keep it on a local interface unless you have added suitable network protection.

Give an agent the authoring guide

picoo skill
picoo skill --out PICOO.md

This prints or saves Picoo’s operation-authoring instructions so an AI coding agent can follow the installed CLI’s conventions.

When a command fails

Start with these checks:

1. Run picoo doctor if a runtime is missing.
2. Run picoo show ID and compare your input names and types with the contract.
3. Use --offline to tell local problems apart from Registry or network problems.
4. Check that required environment variables are set, but do not print secret values.
5. Add --help to the failing command to confirm the available flags.