| name | remote-api-builder |
| description | Use when an agent is building their own implementation of (parts of) the Remote.com partner API in any stack — Python/TS/Ruby/Go HTTP client, OpenAPI spec, Slack/Teams bot, migration script from another HR system, conformance test, or any service that needs to call Remote.com from somewhere other than the existing remotecli binary. Triggers on prompts like "build a Python client for Remote", "wrap Remote in our backend", "generate an OpenAPI spec from remotecli", "reverse-engineer the Remote API", "implement an Authorize-with-Remote button", "bulk-onboard employees from this CSV." Does NOT trigger on operator prompts ("hire Alice", "approve their time off") — those use the remote-cli skill instead. |
remote-api-builder
Use remotecli as a self-documenting executable spec of the Remote.com partner API. Drive it to discover the surface, capture HTTP, translate to your stack, and verify against the CLI as oracle.
When to use this skill
| Prompt pattern | Use this skill? |
|---|
| "Build a Python/TS/Ruby/Go client for Remote.com" | Yes |
| "Generate an OpenAPI spec / SDK from remotecli" | Yes |
| "Add an 'Authorize with Remote' button to our app" | Yes |
| "Wrap Remote in our backend service / Slack bot / migration script" | Yes |
| "How do I authenticate with Remote from " | Yes (see references/auth-bootstrap.md) |
| "Hire Alice in Portugal" / "approve their time off" / any operator action | No — use the remote-cli skill instead |
The methodology
Five steps. The skill's references map to them.
| Step | Primary command(s) | What you learn |
|---|
| Inventory | remotecli describe commands | Every command, its flags, the HTTP endpoints it invokes, the doc URL |
| Plan | remotecli describe schemas + remotecli --plan --answers <seed> | Form fields, enum options, conditional branches, country variations |
| Trace | remotecli <cmd> --trace 2>trace.log (against sandbox) | Real HTTP — headers, body, status, timing |
| Translate | references/translation-patterns.md + references/auth-bootstrap.md | Equivalent code in your stack |
| Verify | references/oracle-workflow.md | Diff your implementation against remotecli; the CLI is your contract test |
Getting started (3 steps)
export REMOTE_ENVIRONMENT=sandbox
remotecli login
remotecli use
remotecli describe commands
No partner credentials required for most builders. For the full walkthrough including the rare partner-credentials path, see references/sandbox-setup.md.
Use the CLI vs. build your own
Two axes interact: what you're building, and who's authorizing.
What you're building:
| Situation | Recommendation |
|---|
| Web / desktop / mobile app — including your own personal dashboard | Build your own client and implement PKCE. The "Authorize with Remote" button is the right UX, even when the only user is you. |
| Long-running backend service (worker, webhook receiver) | Build your own HTTP client. PKCE for the initial consent, refresh-token grant for autonomous operation. |
| Serverless function / Lambda | Build your own — binary distribution is friction. |
| Truly headless one-shot script (CSV import, cron job, no UI ever) | Build your own HTTP client. Do the one-time PKCE consent locally to capture a refresh token, then store it in your service's secret store and use the refresh-token grant from then on. |
| Integrating once, manually, ad-hoc | remotecli interactive mode + the remote-cli skill. |
Who's authorizing → auth flow:
| Your tool | Flow | Reference |
|---|
| Has any login UI — the default | PKCE — "Authorize with Remote" button | references/auth-bootstrap.md § PKCE |
| Production service after one-time human consent | Refresh-token grant on top of PKCE | references/auth-bootstrap.md § refresh-token |
| Headless script you run yourself | Refresh-token grant (do PKCE once to capture, then reuse the refresh token) | references/auth-bootstrap.md § refresh-token |
| Remote partner provisioning new companies | client_credentials + JWT assertion | references/auth-bootstrap.md § partner |
Step 1 — Inventory
remotecli describe commands
remotecli describe commands --name time-off
remotecli describe commands --name 'time-off create'
Each entry: name, summary, flags[], endpoints[].{method,path,doc_url}, forms[] (empty when non-schema-driven), role_required.
Use it as a TOC. The doc_url deep-links into developer.remote.com/reference/<endpoint> when known. See references/discovery-loop.md for a worked walkthrough.
Step 2 — Plan
For schema-driven commands (employments create, contract-amendments create, employments update-personal-details), discover required fields without calling the API:
echo '{"contract_amendment":{}}' > /tmp/seed.json
remotecli --answers /tmp/seed.json --plan contract-amendments create --employment-id emp_abc123
For URL templates (without calling the API):
remotecli describe schemas --country GBR
See references/discovery-loop.md.
Step 3 — Trace
Run the real command against sandbox and capture every HTTP request/response:
remotecli time-off create --employment-id emp_abc \
--timeoff-type time_off --start-date 2026-06-01 --end-date 2026-06-01 \
--trace 2>trace.log
--trace redacts secrets by default (Authorization, refresh_token, client_secret, code_verifier all masked). Never paste trace output anywhere public without re-confirming --insecure-log-secrets is off.
Hard gate: no code before traces
You cannot write implementation code until you have run --trace on every endpoint you plan to call. For each endpoint, record from the actual trace output — not from docs, not from memory, not from translation-patterns.md examples:
| Endpoint | Required query params | Response envelope | Key field names on objects |
|---|
e.g. GET /v1/timeoff | (none — trace confirmed) | data.timeoffs[] | employment_id, start_date, end_date, status |
Fill this table before writing a single function. If you cannot fill a row from a trace, run the trace first.
Why this matters: translation-patterns.md contains illustrative examples. The actual server may require different params (e.g. company_id), use different field names (e.g. full_name not name), or reject param combinations that look reasonable (e.g. comma-joined status values). Only a trace tells you what the server actually accepts and returns.
Step 4 — Translate
Take the trace output you captured in Step 3 and match it to your stack. references/translation-patterns.md shows the mechanical translation patterns (GET / POST / PATCH / PUT / multipart) in Python and TypeScript — use it as a HOW-TO guide for converting a trace into code, not as a substitute for getting a trace. See references/auth-bootstrap.md for the auth side — PKCE in your own app is the default; three other flows cover specific cases.
Step 5 — Verify
Run your implementation alongside remotecli against the same operation, diff the JSON outputs. See references/oracle-workflow.md.
Anti-patterns
- Don't use reference docs or examples as a substitute for traces.
translation-patterns.md shows HOW to translate a trace into code — it is not a spec for what the server accepts. Required query params, field names, and response shapes vary by endpoint and environment. A field called name in an example may be full_name in reality. A status filter that looks composable may reject comma-joined values. Only --trace output is authoritative. If you find yourself writing code based on what "seems right" from docs, stop and run the trace.
- Don't invent query parameters. If you didn't see a param in a trace, don't send it. If you think filtering would be useful, check whether the CLI flag for it exists (
describe commands), then trace it to confirm the wire format.
- Default to PKCE in your own app for any tool with a UI — including your own personal dashboards, not just multi-tenant products. The "Authorize with Remote" button experience is exactly what
remotecli login already does; mirror it. Use internal/auth/pkce.go as your reference implementation, and for personal tools you can piggyback on the CLI's client_id + port 8488 redirect URI to skip allowlist registration entirely. See references/auth-bootstrap.md § PKCE.
- Don't read
~/.remote-cli/state.json from your application. That file is remotecli's private local cache — convenient when prototyping on your own laptop, but not deployable: it doesn't exist on a server, it carries your developer identity (not your users'), and the tokens rotate out from under you whenever the CLI runs. Always implement PKCE (for any tool a human signs into) or the refresh-token grant (for autonomous services), and persist tokens in your own store. See references/auth-bootstrap.md.
- Don't reimplement refresh from scratch. Once you have a refresh token, the refresh-token grant is
POST {authURL}/oauth2/token (PKCE-issued) or {authURL}/auth/oauth2/token (confidential-client), with client_id in a Basic auth header — not the body. Mirror the CLI's 60-seconds-before-expiry proactive-refresh rule.
- Don't hard-code field names. Schemas are country-aware;
--plan is the source of truth. A field that exists in GBR may not exist in USA.
- Don't paste
--trace output publicly without confirming was NOT set on the run that produced it. Redaction is on by default; the flag opts out.
Gotchas
- Minor units.
annual_gross_salary is in pence/cents. 7200000 = £72,000.
- PUT replaces, PATCH merges.
employments update-personal-details replaces the whole personal_details object — partial payloads wipe other fields. Read-modify-write or use the existing CLI.
- Country codes are 3-letter ISO.
GBR not GB, USA not US.
- Role restrictions.
expenses approve, time-off approve, terminations create require manager/admin/owner tokens. Employee tokens get 403.
- Idempotency. Most
create endpoints are NOT idempotent (no built-in dedup key). See references/idempotency.md.
Sandbox posture
Always exercise against REMOTE_ENVIRONMENT=sandbox for Trace and Verify. remotecli login honours REMOTE_ENVIRONMENT — switching is export REMOTE_ENVIRONMENT=production && remotecli login, no other config. See references/sandbox-setup.md.
External docs
- developer.remote.com — developer portal home (guide articles)
- API reference — canonical per-endpoint catalogue. The
doc_url field in describe commands deep-links into this.
- OAuth & auth concepts (auth section of the portal) — when you need the protocol-level detail
The reference is a cross-check, not the starting point. Methodology steps 1-3 do the discovery.
References
references/sandbox-setup.md — the 3-step quickstart in detail (no partner creds)references/discovery-loop.md — Inventory + Plan with one worked examplereferences/translation-patterns.md — HOW to translate a captured trace into Python/TS code; not a substitute for running traces yourselfreferences/auth-bootstrap.md — auth flows; PKCE in your own app is the default, three others cover specific casesreferences/oracle-workflow.md — using remotecli as a contract testreferences/idempotency.md — per-command safe-to-retry tablereferences/common-errors.md — HTTP 4xx catalogue → interpretation → debug command
