onecli-gateway · diff
git:20260507.4305c6a to v0.5.0
53 added, 35 removed. Audit A to A.
---
name: onecli-gateway
description: >-
- Handle credentials and authentication for external services. Use when you
- hit a 401, 403, or app_not_connected error, or when the user asks you to
- access an external service (Gmail, GitHub, Slack, Calendar, Stripe, etc.).
- Do NOT use browser extensions or manual auth flows — make HTTP requests
- directly; the OneCLI proxy injects credentials automatically.
+ OneCLI Gateway: transparent HTTPS proxy that injects stored credentials
+ into outbound calls. You MUST use this skill when the user asks you to
+ read emails, check calendar, access GitHub repos, create issues, check
+ Stripe payments, or interact with ANY external service or API. Do NOT
+ use browser extensions or OAuth CLI tools. Make HTTP requests directly;
+ the gateway injects credentials automatically.
+ compatibility: Requires HTTPS_PROXY set in environment (automatic when launched via `onecli run`)
+ metadata:
+ author: onecli
+ version: "0.5.0"
---
- # OneCLI Gateway: Credentials & Authentication
+ # OneCLI Gateway
- Your container routes all HTTPS traffic through the OneCLI proxy, which
- injects stored credentials (API keys, OAuth tokens) at the proxy boundary.
- You never see or handle credential values directly.
+ Your outbound HTTPS traffic is transparently proxied through the OneCLI
+ gateway, which injects stored credentials at the proxy boundary. You never
+ see or handle credential values directly.
+ ## How to Access External Services
+
+ You have direct HTTP access to external APIs. OAuth apps (Gmail, GitHub,
+ Google Calendar, Google Drive, etc.) and API key services are all available
+ through the gateway. Just make the request directly; the gateway injects
+ credentials if the app is connected. If not, it returns an error with a
+ connect URL you can present to the user.
+
## Making Requests
- Call the real API URL. The proxy intercepts and injects credentials automatically.
+ Call the real API URL. The gateway intercepts the request and injects
+ credentials automatically.
```bash
curl -s "https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=5"
curl -s "https://api.github.com/user/repos?per_page=10"
curl -s "https://api.stripe.com/v1/charges?limit=5"
```
- Any HTTP client (curl, fetch, axios, Python requests, Go net/http, git) honors
- `HTTPS_PROXY` automatically. You do not need to set auth headers.
-
- If a tool or library validates credentials locally before making the request,
- pass any placeholder value (a fake string). The proxy replaces it with real
- credentials at request time.
+ Standard HTTP clients (curl, fetch, requests, axios, Go net/http, git) all
+ honor the `HTTPS_PROXY` environment variable automatically. You do not need
+ to set any auth headers.
- ## When a Request Fails (401 / 403 / app_not_connected)
+ ## Credential Stubs for MCP Servers
- ### Step 1 — Show the user a connect link
+ Some MCP servers need local credential files to start. Stubs for connected
+ apps are pre-written automatically. Files containing `"onecli-managed"`
+ values are managed by OneCLI — do NOT modify or delete them.
- If the error response includes a `connect_url`, share it directly:
+ If an MCP server won't start due to missing credentials, create stubs
+ **before** starting it. Use `"onecli-managed"` as the placeholder for all
+ secret values, with file permissions `0600`. See the guide at:
+ https://www.onecli.sh/docs/guides/credential-stubs/general-app
- > To connect [service], open this link:
- > [connect_url from the error response]
+ ## When a Request Fails
- If there's no `connect_url`, tell the user to open the OneCLI dashboard and
- connect the service there.
+ If you get a 401, 403, or a gateway error (e.g., `app_not_connected`):
- Do NOT ask the user for API keys or tokens. Do NOT suggest pasting credentials
- into chat. The fix is always connecting the service in OneCLI.
+ **Step 1 — Show the user a connect link.** Use the `connect_url` from the
+ error response:
- ### Step 2 — Retry after the user connects
+ > To connect [service], open this link:
+ > [connect_url from the error response]
- After showing the link, let the user know you'll retry once they've connected.
- When they confirm (or after a reasonable pause), retry the original request.
+ If there is no `connect_url` in the error, tell the user to open the
+ OneCLI dashboard and connect the service there.
- If the retry still fails, ask the user if they need help with the OneCLI setup.
+ **Step 2 — Retry after the user connects.** Let the user know you will
+ retry once they have connected. When they confirm, retry the original
+ request. If the retry still fails, ask if they need help with the setup.
## Rules
- **Never** say "I don't have access to X" without first making the HTTP
request through the proxy.
- - **Never** use browser extensions, gcloud, or manual auth flows. The proxy
- handles credentials for you.
- - **Never** ask the user for API keys, tokens, or passwords directly.
+ - **Never** use browser extensions, gcloud, or manual auth flows. The
+ gateway handles credentials for you.
+ - **Never** ask the user for API keys or tokens directly. Direct them to
+ connect the service in the OneCLI dashboard.
- **Never** suggest the user open Gmail/Calendar/GitHub in their browser
when they ask you to read or interact with those services. You have API
- access — use it.
- - If the proxy returns a policy error (403 with a JSON body), respect the
- block. Do not retry or circumvent it.
+ access. Use it.
+ - If the gateway returns a policy error (403 with a JSON body), respect
+ the block. Do not retry or circumvent it.