Metadata-Version: 2.4
Name: oya-cli
Version: 0.4.2
Summary: Build, deploy, debug, and share AI agents on the Oya runtime — from your terminal.
Author-email: Oya <founders@oya.ai>
License-Expression: MIT
Project-URL: Homepage, https://oya.ai
Project-URL: Documentation, https://oya.ai/docs
Keywords: oya,agent,ai,claude-code,automation,runtime
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.25
Requires-Dist: pyyaml>=6.0

# oya-cli

**Build, debug, and ship AI agents on the [Oya runtime](https://oya.ai) — 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.

```sh
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:

```sh
oya quickstart
```

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

---

## The CLI

Read commands (debug):

```sh
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:

```sh
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):

```sh
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:

```sh
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:

```sh
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

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

Then:

```sh
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):

```sh
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
