Write your first op

This walks through creating a real op (a Python script that echoes back a greeting) from scratch.

1. Scaffold it

picoo create demo/greet \
  --runtime python \
  --description "Say hello to someone" \
  --input name:string

This writes a manifest and a starter script to ~/.picoo/ops/demo/greet/:

• picoo.toml: the manifest (name, description, runtime, input schema, permissions)
• main.py: a starter script using PEP 723 inline dependencies, so uv can run it with zero setup

2. Implement it

Open ~/.picoo/ops/demo/greet/main.py. The starter already parses stdin as JSON and prints a {"result": ...} envelope. Just fill in the logic:

def main():
    request = json.load(sys.stdin)
    name = request["name"]
    result = {"greeting": f"Hello, {name}!"}
    print(json.dumps({"result": result}))

Errors work the same way: raise an exception and the starter’s except block turns it into {"error": {"code": "unhandled", "message": "...", "retryable": false}} with exit code 1, no extra wiring needed.

3. Run it

picoo run demo/greet --input name=Nahid

{
  "result": {
    "greeting": "Hello, Nahid!"
  }
}

Missing a required input? picoo validates against the manifest before it even starts the subprocess, so you get a fast, precise error instead of a stack trace from inside your script.

4. Iterate

Change your mind about the description or add an input later without touching the script:

picoo update demo/greet --description "Say hello, loudly"

5. Find it again

Once you (or an agent) have more than a handful of ops, picoo list and picoo show demo/greet are fine for browsing, but picoo search is built for an agent that only remembers roughly what an op does:

picoo search "send a greeting" --top 3

Each hit returns enough (id, description, input schema) to construct a picoo run call directly, with no follow-up show needed.

See the CLI reference for every flag.