Metadata-Version: 2.4
Name: oya-cli
Version: 0.2.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 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.

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

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

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

Skill catalog:

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

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