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 scaffolds a brand-new skill folder via oya skill create plausible, edits the SKILL.md + script.py, then attaches the folder to your agent in one step with oya agent skills add <agent_id> ./plausible/. The skill is now reusable across all your future agents.
• "Fork this agent: https://gist.githubusercontent.com/.../my-sdr.oya.yaml" — 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 <id> <skill_id_or_path>  # folder path imports + attaches in one step
oya agent skills update <id> <skill_id> --values config.yaml --secrets .env
oya agent skills remove <id> <skill_id>
oya agent skills sync <id> --skills-dir ./skills/   # or --skills-json - for automation
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.yaml       # portable YAML spec, credentials stripped
oya agent fork ./agent.oya.yaml               # clone from a local file
oya agent fork https://gist.../agent.oya.yaml # clone from a URL

The OyaAgentSpec v1 format covers soul + skills + routines + (optional) KB, expressed as YAML. Drop one in a gist or repo and anyone with oya-cli can oya agent fork <url> to clone it. Legacy .oya.json specs still parse (YAML is a JSON superset).

Templates:

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

Skills — author, validate, ship:

oya skill create my-plausible                 # interactive scaffolder; drops SKILL.md + script.py + .env.example + .gitignore
oya skill validate ./my-plausible/            # lint frontmatter before upload (kebab-case, tool_schema, entry point, no __pycache__)
oya agent skills add <id> ./my-plausible/     # import + attach in one step
oya list                                      # all skills available in your account
oya export <skill_id> out.zip                 # download a skill (oya format)
oya export <skill_id> out.zip --format anthropic  # publish-ready Claude Code Agent Skill subset
oya import ./my-skill/                        # upload-only (no attach) — useful for sharing a skill into your account first

A skill is a folder: SKILL.md (YAML frontmatter — tool_schema, config_schema, resource_requirements) plus script.py (or scripts/ for multi-file), optional references/ and assets/. The same folder is loadable by Claude Code from ~/.claude/skills/ — the SKILL.md spec is shared, and Claude Code ignores the Oya-specific frontmatter keys.

Per-agent values live in sidecar files next to SKILL.md (auto-detected by oya agent skills add): .env for resource_requirements (gitignored), config.local.yaml for config_schema. Anything missing is prompted from the frontmatter contract. For scripted attach, pass them explicitly with --values FILE --secrets FILE --non-interactive.

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.yaml — 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: founders@oya.ai
• License: MIT