> ## Documentation Index
> Fetch the complete documentation index at: https://www.keycli.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Provider connections

> Connect one provider well before expecting live execution from Keycli.

Connect one provider well. Do not connect everything first.

## Recommended first provider

Start with **Vercel**.

Why:

* easiest first live proof
* preview-safe path exists
* clear project scope

## Usage order

1. `npm install`
2. start the hosted API with `npm run api:hosted`
3. create one scoped provider connection through the hosted API
4. test it
5. inspect readiness
6. only then create live plans

## Canonical setup path

Today, the governed engine behind Keycli lives in the hosted `src-ts` path.

Public onboarding is still repo-first. The hosted API is canonical, and the current public wedge may be driven either through the hosted HTTP API directly or through the thin repo CLI shape that talks to it.

Start here first:

```bash theme={null}
npm install
npm run api:hosted
```

If you are following the Vercel wedge docs, `node src/cli.mjs ...` is acceptable as the current thin entrypoint into that hosted workflow.

## Create a scoped connection

Use the hosted API to create one scoped connection at a time:

```bash theme={null}
curl -s -X POST http://localhost:8788/v1/connections \
  -H "authorization: Bearer $KEYCLI_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "provider": "vercel",
    "label": "main",
    "authMethod": "api_token",
    "credentialRef": "env:VERCEL_TOKEN",
    "scope": {
      "provider": "vercel",
      "project": "demo-app"
    }
  }'
```

Other current scope shapes:

* GitHub: set `"provider": "github"` and `"scope": { "provider": "github", "repository": "demo-org/demo-app" }`
* Render: set `"provider": "render"` and `"scope": { "provider": "render", "serviceId": "srv-demo" }`

## Inspect what is connected

```bash theme={null}
curl -s http://localhost:8788/v1/connections \
  -H "authorization: Bearer $KEYCLI_TOKEN"

curl -s http://localhost:8788/v1/capabilities \
  -H "authorization: Bearer $KEYCLI_TOKEN"
```

## Current scope shapes

* Vercel: `{ "provider": "vercel", "project": "your-project" }`
* GitHub: `{ "provider": "github", "repository": "org/repo" }`
* Render: `{ "provider": "render", "serviceId": "srv-..." }`

## If live execution is not available

Usually it is one of these:

* missing connection
* invalid credentials
* scope mismatch
* unsupported target

Fix the connection story first.

## Next reads

* [First governed change](./first-governed-change)
* [Approvals](./approvals)
* [Vercel](./VERCEL)
* [GitHub](./GITHUB)
* [Render](./RENDER)