remote-api-builder

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              # PKCE browser flow — opens your browser
remotecli use                # pick the company you want to operate against
remotecli describe commands  # you're now exploring the API

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                       # everything
remotecli describe commands --name time-off       # prefix-filter
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
# → {"type":"plan","data":{"ok":false,"missing":[...],"invalid":[...],"answers":{...}}}

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 example
• references/translation-patterns.md — HOW to translate a captured trace into Python/TS code; not a substitute for running traces yourself
• references/auth-bootstrap.md — auth flows; PKCE in your own app is the default, three others cover specific cases
• references/oracle-workflow.md — using remotecli as a contract test
• references/idempotency.md — per-command safe-to-retry table
• references/common-errors.md — HTTP 4xx catalogue → interpretation → debug command