oya-cli 0.2.2

Build, deploy, debug, and share AI agents on the Oya runtime — from your terminal.

oya-cli

Build, debug, and ship AI agents on the Oya runtime — from your terminal or from Claude Code.

Oya is an agent runtime: you describe an agent, we deploy it in a sandbox, expose it via chat, webhooks, schedules, or an OpenAI-compatible API. oya-cli is the developer-side surface — and the engine behind the bundled Oya Claude Code skill, which turns Claude Code into the fastest place to ship and debug Oya agents.

---

The Claude Code experience

Install once, then ask Claude Code things like:

• "Build me a Facebook SDR agent for my SaaS" — Claude Code picks the closest template, customizes the persona / rules / skills / routines / KB, walks you through gateway OAuth, and deploys. Chat URL printed at the end.
• "Why did my AI SDR routine fail at 2am?" — lists recent failed runs, drills into the failed job_id, reads the full stdout/stderr, matches the symptom against a built-in failure cookbook (missing creds / auth expired / rate limit / rule conflict / overdue routine / silent error), proposes a fix, asks you to confirm, executes, re-runs, confirms green.
• "Add a daily 9am pipeline summary routine to my SDR" — Claude Code edits the agent and redeploys.
• "My agent needs to call the Plausible API and there's no skill for it" — Claude Code authors a brand-new sandbox skill (SKILL.md + script.py), uploads it via oya import, and attaches it to your agent. The skill is now reusable across all your future agents.
• "Fork this agent: https://gist.githubusercontent.com/.../my-sdr.oya.json" — clones a portable agent spec into your account.

The skill ships with reference cookbooks (failure patterns, skill catalog grouped by use case, gateway OAuth flows, persona/rules patterns) so the model has the same context an experienced Oya engineer would.

pipx install oya-cli
oya login                       # save your API key from oya.ai/api-keys
oya install-claude-skill        # copies the skill to ~/.claude/skills/oya/

That's it. Open Claude Code, ask anything above.

---

The 60-second build

Even without Claude Code:

oya quickstart

Describe what you want, pick a template, walk one OAuth, ship. Chat URL printed at the end.

---

The CLI

Read commands (debug):

oya agent list                           # your agents
oya agent runs <id> --status failed      # recent failures with job_ids
oya agent run <id> <job_id>              # full payload + stdout/stderr/error
oya agent thread <thread_id>             # chat history including tool calls
oya agent trace <trace_id>               # Langfuse LLM trace
oya agent skills list <id>               # skills + credential presence
oya agent gateway list <id>              # connected platforms
oya agent routine list <id>              # scheduled prompts + last/next run
oya agent kb list <id>                   # KB entries assigned to the agent

Edit commands:

oya agent soul <id> --persona "..." --rule "..." --rule "..." --welcome "..."
oya agent skills add/update/remove/sync <id> ...
oya agent gateway connect <id> <platform>     # OAuth (or pick existing connection)
oya agent routine add <id> --name --schedule --prompt
oya agent routine update <routine_id> --prompt --schedule --enabled
oya agent kb upload <id> <file> --folder "..."
oya agent kb delete <entry_id>
oya agent deploy <id>
oya agent run-script <id> --message "..."     # re-run; returns job_id
oya routine run <routine_id>                  # manually trigger a routine

Viral primitives (share + clone agents like Dockerfiles):

oya agent export <id> -o agent.oya.json       # portable spec, credentials stripped
oya agent fork ./agent.oya.json               # clone from a local file
oya agent fork https://gist.../agent.oya.json # clone from a URL

The OyaAgentSpec v1 format covers soul + skills + routines + (optional) KB. Drop one in a gist or repo and anyone with oya-cli can oya agent fork <url> to clone it.

Templates:

oya template list
oya template get ai-sdr
oya agent template apply ai-sdr <agent_id>    # replay template onto an agent

Skill catalog:

oya list                                      # all skills available in your account
oya export <skill_id> out.zip                 # download a skill
oya import ./my-skill/                        # upload a custom skill (folder with SKILL.md)

oya <command> --help for full reference on any subcommand.

---

The Claude Code skill, in detail

Installed at ~/.claude/skills/oya/:

• SKILL.md — instructions Claude reads when the skill is triggered. Three flows: debug (the killer feature), edit, build.
• references/failure-cookbook.md — 10+ symptom→cause→fix patterns drawn from real production failure modes.
• references/skill-catalog.md — 80+ skills grouped by use case (Sales SDR, Exec Assistant, Marketing, Discord support, ...) with canonical pairings ("for an AI SDR, attach these 9 skills").
• references/gateway-cookbook.md — per-platform OAuth flow and common auth-failed messages.
• references/agent-cookbook.md — what good personas, behavior rules, and welcome messages look like, with examples to imitate and anti-patterns to avoid.
• references/skill-authoring.md — how to write and ship a brand-new sandbox skill when nothing in the catalog fits.
• examples/{ai-sdr,exec-assistant,support-bot}.oya.json — forkable starter specs.

The skill enforces a "complete agent" bar — soul + 8–14 skills + ≥2 routines + KB + gateways — before deploy. No half-built toys.

---

Install

pipx install oya-cli
# or
pip install oya-cli

Then:

oya login                       # browser opens, you paste a key from oya.ai/api-keys
oya install-claude-skill        # for the Claude Code experience

For local development of the skill (live edits without reinstalling):

oya install-claude-skill --link --force

Config

Variable	Purpose
OYA_API_TOKEN	Your API key. Stored at ~/.oya/config.json after oya login.
OYA_API_URL	Defaults to https://oya.ai. Set to https://dev.oya.ai for the dev environment.

Links

• Runtime: https://oya.ai
• Docs: https://oya.ai/docs
• Support: [e-mail]
• License: MIT