# Yutori AI Agent Quickstart

You are helping a user set up Yutori from scratch. Yutori provides APIs and agent tools for:

| Capability | Use it for |
| --- | --- |
| Scout | Continuous web monitoring on a schedule |
| Research | One-time deep web research |
| Browsing | One-time browser automation |
| Navigator | A computer-use model API for custom browser agents |

Prioritize the CLI/MCP setup first. Do not ask the user to paste API keys into chat.

## Setup

Drive setup yourself. The user's only action is clicking **Allow** in a browser tab that opens during auth.

1. Install the CLI, MCP server, and skills in one shot (you run this):

    ```bash
    YUTORI_INSTALL_CLIENT=<client> curl -fsSL https://yutori.com/install.sh | bash
    ```

    Substitute `<client>` with your agent's slug — common values: `claude-code`, `codex`, `cursor`, `vscode`, `claude-desktop`, `gemini-cli`, `zed`, `opencode` (run `npx add-mcp list-agents` for the full list). If `YUTORI_INSTALL_CLIENT` is unset the installer registers MCP for the default set (`claude-code`, `codex`, `cursor`, `gemini-cli`).

    In non-TTY mode the installer does the CLI install via `uv tool install yutori`, registers the Yutori MCP server for the chosen client(s), and installs the six workflow skills (`yutori-scout`, `yutori-research`, `yutori-browse`, `yutori-competitor-watch`, `yutori-api-monitor`, `yutori-login`) at user scope. Auth and verification are skipped — they need a browser and an API key (step 2 below).

    If `~/.local/bin` isn't on your PATH yet, invoke `yutori` via `$(uv tool dir --bin)/yutori` or run `export PATH="$(uv tool dir --bin):$PATH"` for the rest of this session.

2. Authenticate (you run this; **user clicks Allow**):

    ```bash
    yutori auth login
    ```

    **Always run this yourself first**, even on a headless host. The command calls `webbrowser.open(auth_url)`, binds `127.0.0.1` for the OAuth callback, and saves the API key to `~/.yutori/config.json`. The Bash call blocks for up to 5 minutes waiting for the user — if it times out, rerun.

    Two cases:
    - **Desktop / browser available**: the sign-in tab opens automatically. Tell the user: *"I'm opening a Yutori sign-in tab — click Allow when it loads."*
    - **Headless host / no browser**: the command prints `Could not launch a browser` followed by an `auth_url`. **Relay that URL to the user** — they paste it into a browser on their own machine, click Allow, and the OAuth callback still completes through your Bash process. Don't skip running `yutori auth login` just because the host might be headless; try it and react to what it prints.

3. Ask the user to restart this coding agent so the MCP tools and skills load.

### Fallback: if step 1 didn't configure MCP or skills

The installer's status table will say `MCP server: SKIP` or `MCP skills: SKIP` if Node.js/npx wasn't on PATH. Run only the failed step(s):

```bash
# MCP server
npx add-mcp -y -g -n yutori -a <client> "uvx yutori-mcp"

# Workflow skills
npx skills add yutori-ai/yutori-mcp -g
```

If `npx` isn't available, native CLIs work for some clients:
- Claude Code: `claude mcp add --scope user yutori -- uvx yutori-mcp`
- Codex: `codex mcp add yutori -- uvx yutori-mcp`

**Fallback path:** if your Bash tool can't bind `127.0.0.1` for the auth callback (remote dev environment, sandboxed agent) or the user is on a different machine, ask the user to run `curl -fsSL https://yutori.com/install.sh | bash` in their own terminal — the interactive installer walks through CLI, auth, MCP, skills, and a verification task end-to-end.

## Verify

**You run these yourself** once the user confirms `yutori auth login` completed:

```bash
yutori auth status     # confirms the API key is saved and valid
yutori usage           # shows the user their daily quota and active scouts
```

If both succeed, proceed to **Demonstrate** below. If MCP tools have already loaded in your session (i.e. the coding agent was restarted), `list_api_usage` is an equivalent MCP check.

## Demonstrate

After auth and verify succeed, run the three demos yourself via the `yutori` CLI in your Bash tool — **no coding-agent restart needed**. (After restart, the MCP tools `run_research_task`, `run_browsing_task`, `create_scout` and the `/yutori-*` skills also become available; use either path.)

The task APIs are async: `run` starts the task and returns a `task_id`; you then poll `get TASK_ID` until `status` is `succeeded` or `failed`. Examples below mirror the canonical queries at <https://docs.yutori.com/reference/> so demo and docs stay aligned.

### Research (3–10 min)

```bash
yutori research run "What are the latest developments in quantum computing from the past week? Include company announcements, research papers, and product releases."
# returns task_id; poll until done
yutori research get <task_id>
```

Show the user the returned summary once `status: succeeded`.

### Browsing (30–120 sec)

```bash
yutori browse run "Give me a list of all employees (names and titles) of Yutori." "https://yutori.com"
yutori browse get <task_id>
```

Confirm with the user before running additional browsing tasks — each one spends credits.

### Scout — draft only, **do not auto-create**

Scouts are *recurring* and spend credits on every scheduled run. Show the user the query you would use and ask for explicit confirmation before running:

```bash
yutori scouts create -q "Tell me about the latest news, product updates, press releases, social media announcements, investments into, or other relevant information about Yutori"
```

If they decline, skip the Scout demo and end with a recap of Research + Browsing.

For SDK/API integration details, use:

- Python SDK and CLI reference: https://github.com/yutori-ai/yutori-sdk-python/blob/main/api.md
- MCP server and skill setup: https://github.com/yutori-ai/yutori-mcp
- API docs index for agents: https://docs.yutori.com/llms.txt