Guides

Agents and scripts

Use Workpaper from an AI agent, a script or CI.

Every command works the same without a person at the keyboard. Three things make it script-friendly.

1. `--json` on every command

workpaper exec my-agent --json -- ls /

{
  "id": "my-agent",
  "exit_code": 0,
  "stdout": "bin\nboot\ndev\n...",
  "stderr": ""
}

Errors come back as {"error": "..."} with a non-zero exit code.

2. Exit codes you can trust

workpaper exec exits with the command's own exit code.
Workpaper's own errors exit with 1; wrong usage exits with 2.

3. Nothing ever waits for input

Without a terminal, the CLI never asks questions. For example, a new computer needs a name, and instead of asking for one it tells you how to pass it:

name your new computer: workpaper run my-agent

A typical agent loop

workpaper run task-42 --json            # create or wake
workpaper cp ./repo.tar.gz task-42:     # send files
workpaper exec task-42 -- tar xzf repo.tar.gz
workpaper exec task-42 -- make test     # exit code = test result
workpaper cp task-42:repo/report.txt .  # fetch results
workpaper stop task-42                  # stop paying

Passing secrets

Export a secret on your machine and pass its name with --env. The value goes to the command on the computer without ever appearing in your command line or shell history:

workpaper exec task-42 --env GITHUB_TOKEN -- git clone https://github.com/you/private-repo

Picking a computer by default

Commands that take [name] use the computer you used last. In scripts, be explicit, or set WORKPAPER_NAME.

Telling an AI about Workpaper

Point it at workpaper.co/llms.txt. It's a short plain-text summary written for language models.

Terms · Privacy · Contact