# Set up Scrappycoco

For the AI agent receiving this link: connect this customer to Scrappycoco using
**CLI + Skill by default**. Complete the installation and verification yourself
where your tools permit it; the customer should only need to sign in in their
browser. Follow the client's normal permissions. Never request passwords, API
keys, tokens, or OAuth callback URLs in chat.

Scrappycoco provides deterministic Discover and Run tools. The calling AI owns
provider choice, configuration, and judgment of the returned evidence.

## 1. Check the environment

Use the environment where your terminal commands actually run, which may differ
from the customer's computer. Do not infer terminal access or installed software
from the client name. Do not ask the customer to choose an integration.

- If a working Scrappycoco CLI version 0.8.9 or newer is already installed, use it.
  Check `scrappycoco --version` and the managed launcher below. Run `setup` to
  reuse authentication, install the skill, and verify the connection.
- If Node.js 20+ and npm/npx are available, run:

  ```sh
  npx --yes @scrappycoco/cli@latest setup
  ```

- If Node/npm is missing, too old, or the npm route fails because of local
  permissions or package-manager configuration, use the managed installer below.
  **Do not send the customer away to install Node, npm, Python, or Homebrew.**
- Only use the MCP fallback when terminal execution or local installation is
  unavailable, or when the customer explicitly requests MCP.

## 2. Managed CLI + Skill installation

This path installs a checksum-verified private Node runtime and the published
Scrappycoco CLI under the user's home directory. It does not require sudo, an
existing Node installation, or changes to system Node or shell startup files.
It installs only Scrappycoco's skill for the active agent (a portable shared
location when the agent cannot be identified).

macOS or Linux, using the agent's shell:

```sh
(
installer=$(mktemp) || exit 1
trap 'rm -f "$installer"' EXIT
curl --proto '=https' --tlsv1.2 -fsSL https://scrappycoco.ai/install.sh -o "$installer" && sh "$installer"

)
```

Check the installer's exit status before proceeding. Reading the downloaded
installer before running it is fine.

Windows, using PowerShell:

```powershell
$installer = Join-Path ([IO.Path]::GetTempPath()) ('scrappycoco-' + [Guid]::NewGuid().ToString('N') + '.ps1')
Invoke-WebRequest -UseBasicParsing https://scrappycoco.ai/install.ps1 -OutFile $installer
& $installer
Remove-Item -LiteralPath $installer
```

If script execution is restricted by an organizational policy, do not bypass the
policy. Use the MCP fallback. Shell environment overrides and organization-wide
configuration are not part of setup.

The installer prints the full launcher path. Use it immediately and in future
commands; a running agent does not inherit a new PATH. Defaults:

- macOS/Linux: `~/.local/share/scrappycoco/bin/scrappycoco`
- Windows: `%LOCALAPPDATA%\Scrappycoco\bin\scrappycoco.cmd`

In PowerShell invoke the path with `&`. `--install-only` (PowerShell:
`-InstallOnly`) installs the CLI without opening sign-in; it is **not** completed
setup. Follow it with `setup` using the printed launcher.

## 3. Sign in and verify

Keep the setup process running while the customer completes browser sign-in or
account creation. Show the authorization link if a browser cannot open
automatically. A successful browser page alone does not mean setup completed.

For a remote host, `127.0.0.1` refers to that host, not the customer's browser.
If the customer can enter private input into the same terminal, use
`setup --no-browser --manual-callback` and the terminal's instructions. Do not
have them paste the callback into chat. If there is no suitable private terminal,
use the MCP fallback instead of repeatedly attempting localhost OAuth.

After setup exits successfully, using the **same CLI invocation**:

1. Run `auth status --json`, `skill status --json`, and
   `catalog list --available --json`.
2. Confirm authenticated status, `installed: true`, and a successful catalog
   response. If any check fails, run `doctor --json` and fix that specific issue.
   Do not repeatedly reinstall for an authentication or API outage.
3. Read the installed `SKILL.md` from `skill.path` in the setup result (or `target`
   from `skill status --json`) **in this conversation**, and apply those
   instructions now. Use the same working CLI invocation for the customer's task.
   Do not stop at installing the file or ask the customer to inspect the catalog:
   setup already verified it.

**Do not make restarting the agent a prerequisite for using Scrappycoco.** The
CLI is usable immediately. Reading the skill gives this conversation its
instructions; automatic discovery in future sessions is a separate client
feature. Do not claim automatic registration merely because a file was written.
Only mention a client reload if the client actually reports that automatic skill
discovery requires it, and explain that current CLI use can continue. Do not
infer that requirement from the client name or repeat an older CLI's generic
restart message.

No paid scrape is required to verify setup. Do not create accounts unattended,
add payment methods, start subscriptions, or change unrelated client settings.
When using an existing CI API key, read it from `SCRAPPYCOCO_API_KEY`; never print
it. Ordinary customer setup uses browser sign-in, with no API-key copying.

## MCP fallback: clients without usable local execution

Add Scrappycoco as a remote Streamable HTTP MCP server:

```text
https://api.scrappycoco.ai/mcp
```

Use the client's native add-server or connector flow and browser OAuth. If you
cannot configure it directly, give the customer the client-specific steps from
https://scrappycoco.readme.io/docs/mcp. Do not guess unsupported settings or
promise that every client/account permits custom connectors. Verify that you can
call `list_scrapers`; then use `get_scraper` and `run_scraper` as appropriate.
An MCP-only connection does not require Node, npm, or the CLI skill. Do not send
that customer back to an npm installer.

## Finish

After verification and reading the skill, give one short, plain-language
confirmation: "Scrappycoco is connected with CLI + Skill and ready to use."
For MCP, state that connection instead. Continue the customer's original task
when one was provided. Keep raw JSON, credential-storage details, package
commands, and capability counts out of the completion message unless requested
or needed to explain a problem.

If sign-in, reading the skill, or another required step did not complete, say
exactly what remains instead of claiming full completion. If neither installation
nor MCP is available, explain the exact limitation and link to
https://scrappycoco.readme.io/docs/installation. Never claim success.