Create your first operation

This guide creates a Python operation that greets one person.

1. Create it

Every operation ID has the form author/app/name. Use lowercase letters, numbers, hyphens, or underscores.

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

Picoo creates a picoo.toml manifest and a starter main.py program. Run picoo show alice/demo/greet to see the manifest and where the files live.

Python, Node, and binary operations are supported. Use --runtime node or --runtime binary when those fit the job better.

2. Add the behavior

Open the generated main.py. Replace its placeholder result with:

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

An operation reads one JSON object from standard input. It writes either a successful result or a structured error as JSON.

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

3. Run it

picoo run alice/demo/greet --input name=Nahid

Picoo checks the input and output against the manifest. A missing input, a wrong type, or an undeclared output produces an error instead of a silent mismatch.

4. Change its contract

Use picoo update when the description, version, permissions, or schema changes.

picoo update alice/demo/greet \
  --description "Return a friendly greeting" \
  --version 0.2.0 \
  --input name:string \
  --input excited:boolean? \
  --output greeting:string

The ? makes an input optional. When you pass any --input or --output flag to picoo update, that group replaces the whole existing schema. Include every field you want to keep.

5. Declare access before using it

An operation must declare the access it needs. This makes review easier and lets Picoo enforce policy when the operation is sandboxed.

picoo create alice/weather/current \
  --runtime python \
  --description "Get the current weather" \
  --input city:string \
  --output temperature:number \
  --network api.weather.example \
  --auth weather \
  --secret-env WEATHER_API_TOKEN

Use --environment NAME only for non-secret environment variables the operation must read. Keep tokens and passwords in --secret-env, and never put their values in the manifest.

6. Check it before sharing

picoo show alice/demo/greet
picoo run alice/demo/greet --input name=Nahid --sandbox

--sandbox asks Picoo to enforce the declared permissions with the operating system sandbox. If the required sandbox is unavailable, Picoo stops instead of running without it.

When the operation is ready, continue to the Registry guide.

Recap

You created a typed operation, implemented its JSON contract, ran it locally, updated its version, and reviewed its declared access. Next, publish it through the Registry.