CLI Reference

Both the TypeScript (papayya) and Python (papayya) CLIs share the same command structure.

# TypeScript
npm install -g papayya
 
# Python
pip install papayya

Commands

configure

Set up CLI authentication with an API key from the Dashboard (opens in a new tab).

papayya configure       # TypeScript
papayya configure           # Python

Prompts for your API key (hidden input) and an optional API URL. Validates the key against the backend and saves config.

login is available as a backwards-compatible alias.

init

Scaffold a BYOF agent file into the current directory.

papayya init --name my-agent          # TypeScript → agent.ts
papayya init --name my-agent          # Python → agent.py, requirements.txt, .env.example

The scaffolds show the BYOF pattern: you construct your own ModelClient (TS) or call your LLM SDK directly inside a durable task (Python). Papayya does not ship provider adapters, so the scaffold imports the provider SDK you choose.

run

Trigger a run in the cloud runtime. Local execution is not handled by this command — run your agent file directly (npx tsx agent.ts or python agent.py), since your code owns the LLM call.

# Cloud run
papayya run --input "Research AI trends" --cloud
 
# Python — cloud
papayya run --file agent.py --input "Research AI trends" --agent-id <id>

papayya run --local prints an error explaining the BYOF model — execute your agent file with npx tsx / python instead.

papayya deploy

Deploy an agent to the Papayya cloud. Auto-discovers @agent functions in your code, looks up or creates the agent by slug, bundles the code, builds a container image, and uploads it.

# Zero-arg — discovers agent.py in cwd and all @agent functions in it
papayya deploy
 
# Explicit file
papayya deploy agent.py
 
# CI/CD — use env vars instead of interactive config
PAPAYYA_API_KEY=cpk_... PAPAYYA_PROJECT_ID=... papayya deploy

No --agent-id required — the CLI discovers agent names from @agent decorators and looks them up by slug.

papayya status

Check the status of a cloud run.

papayya status <task-id>

papayya logs

Stream logs from a cloud run.

papayya logs <task-id> --follow

papayya worker

Run a tool worker for cloud execution. The worker polls for pending tool calls and executes them locally.

papayya worker

papayya schedule

Manage cron schedules for agents.

schedule create

papayya schedule create \
  --agent-id ag_abc123 \
  --cron "0 9 * * *" \
  --timezone "America/New_York" \
  --input "Daily research summary" \
  --max-steps 20 \
  --budget-cents 100

schedule list

papayya schedule list --agent-id ag_abc123

schedule get, update, delete, enable, disable

papayya schedule get <schedule-id>
papayya schedule update <schedule-id> --cron "0 */6 * * *"
papayya schedule delete <schedule-id>
papayya schedule enable <schedule-id>
papayya schedule disable <schedule-id>

papayya secrets

Manage project secrets (injected into cloud agent environments).

# Set a secret
papayya secrets set --project-id proj_abc123 MY_API_KEY sk-abc123
 
# List secrets (names only)
papayya secrets list --project-id proj_abc123
 
# Delete a secret
papayya secrets delete --project-id proj_abc123 MY_API_KEY

papayya webhook

Manage webhooks that trigger agent runs from external events.

# Create a webhook
papayya webhook create --agent-id ag_abc123 --name "GitHub Push"
 
# List webhooks
papayya webhook list --agent-id ag_abc123
 
# Delete a webhook
papayya webhook delete <webhook-id>

Configuration

Both CLIs persist config after configure:

Saved fields: api_key, base_url, project_id.

Environment variables

Papayya does not read provider keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, …). Those are read by your LLM SDK, which you import and call inside your agent code.