First Step CLI
Use the CLI as the canonical agent interface to First Step Hub. Do not recreate
OAuth, HTTP, upload, or redaction logic in ad hoc scripts.
Prepare
Resolve and verify the CLI:
command -v first-step || test -x "$HOME/.local/bin/first-step"
first-step --version
If unavailable or stale, run scripts/install-cli.sh. Set
FIRST_STEP_WEB_REPO only when the application repository is not at
~/Developer/first-step-web.
Repository maintainers can run scripts/install-agent-skill.sh to install this
one canonical directory for both Codex and Claude Code. It refuses to overwrite
unrelated existing paths.
Check authentication before protected operations:
first-step auth status
When unauthenticated, run first-step auth login and tell the user that the
system browser will open. Never request, capture, paste, inspect, or print their
Google credentials, authorization code, access token, refresh token, PKCE
verifier, or Keychain contents. Read
references/authentication.md for login or
authentication troubleshooting.
Choose the command surface
- Use
first-step api list and first-step api describe OPERATION_ID to
discover the current OpenAPI-backed catalog.
- Use
first-step api call OPERATION_ID for reads, writes, imports, exports,
downloads, and every other declared API operation.
- Use
first-step html upload, html publish, or html share for standalone
HTML because these commands safely own the multi-step upload/share protocol.
Always run api describe before an unfamiliar operation and before a mutation.
Read references/api-operations.md when selecting
or calling an operation. Read
references/html-workflows.md for HTML work.
Execute safely
- Prefer the configured production origin. Use
--origin only when the user
explicitly selects another environment.
- Treat
authentication: session-only as a browser boundary. Do not bypass it
with cookies, copied tokens, MCP credentials, or custom requests.
- Before a mutation, read the current resource and version, inspect the exact
OpenAPI request schema, preserve optimistic concurrency, and include a clear
change reason where supported.
- Follow preview/commit and confirmation-token flows for financial or other
guarded writes. Never turn a preview request into authority to commit.
- Never hard-delete business records or use generic SQL/arbitrary-table access.
- Put JSON request bodies in scoped files. Keep opaque values out of command
arguments; use
--header-env for sensitive headers.
- Use
--output for CSV/binary responses and exact opaque JSON needed by a
follow-up step. The destination must be new and narrowly scoped. Remove
temporary sensitive output when the operation is complete.
- Do not upload files, publish links, send data, or mutate production merely to
test the CLI. Use read-only checks unless the user's task authorizes the
business change.
Verify and report
Treat a nonzero exit status as failure and parse the single JSON result. After a
mutation, perform the narrowest read-back that proves the intended state.
Report operation IDs, resource IDs/versions, output paths, and URL visibility;
never report secrets.
For HTML, distinguish the authenticated privateUrl from the time-limited
public publicUrl. Do not describe privateUrl as uploader-only: any signed-in
user with documents.read may view it.
1---2name: first-step-cli3description: Operate First Step Hub through the repository-owned `first-step` CLI, including installation, OAuth login/status/logout, discovery and execution of every OpenAPI operation, JSON and binary transfer, and private or public HTML workflows. Use when Codex or Claude needs to inspect, read, create, update, archive, import, export, upload, download, authenticate, troubleshoot, or otherwise automate First Step Hub; trigger on `first-step`, First Step Hub API, CLI authentication, operationId, HTML upload, or HTML sharing requests.4---56# First Step CLI78Use the CLI as the canonical agent interface to First Step Hub. Do not recreate9OAuth, HTTP, upload, or redaction logic in ad hoc scripts.1011## Prepare1213Resolve and verify the CLI:1415```bash16command -v first-step || test -x "$HOME/.local/bin/first-step"17first-step --version18```1920If unavailable or stale, run `scripts/install-cli.sh`. Set21`FIRST_STEP_WEB_REPO` only when the application repository is not at22`~/Developer/first-step-web`.2324Repository maintainers can run `scripts/install-agent-skill.sh` to install this25one canonical directory for both Codex and Claude Code. It refuses to overwrite26unrelated existing paths.2728Check authentication before protected operations:2930```bash31first-step auth status32```3334When unauthenticated, run `first-step auth login` and tell the user that the35system browser will open. Never request, capture, paste, inspect, or print their36Google credentials, authorization code, access token, refresh token, PKCE37verifier, or Keychain contents. Read38[references/authentication.md](references/authentication.md) for login or39authentication troubleshooting.4041## Choose the command surface4243- Use `first-step api list` and `first-step api describe OPERATION_ID` to44 discover the current OpenAPI-backed catalog.45- Use `first-step api call OPERATION_ID` for reads, writes, imports, exports,46 downloads, and every other declared API operation.47- Use `first-step html upload`, `html publish`, or `html share` for standalone48 HTML because these commands safely own the multi-step upload/share protocol.4950Always run `api describe` before an unfamiliar operation and before a mutation.51Read [references/api-operations.md](references/api-operations.md) when selecting52or calling an operation. Read53[references/html-workflows.md](references/html-workflows.md) for HTML work.5455## Execute safely5657- Prefer the configured production origin. Use `--origin` only when the user58 explicitly selects another environment.59- Treat `authentication: session-only` as a browser boundary. Do not bypass it60 with cookies, copied tokens, MCP credentials, or custom requests.61- Before a mutation, read the current resource and version, inspect the exact62 OpenAPI request schema, preserve optimistic concurrency, and include a clear63 change reason where supported.64- Follow preview/commit and confirmation-token flows for financial or other65 guarded writes. Never turn a preview request into authority to commit.66- Never hard-delete business records or use generic SQL/arbitrary-table access.67- Put JSON request bodies in scoped files. Keep opaque values out of command68 arguments; use `--header-env` for sensitive headers.69- Use `--output` for CSV/binary responses and exact opaque JSON needed by a70 follow-up step. The destination must be new and narrowly scoped. Remove71 temporary sensitive output when the operation is complete.72- Do not upload files, publish links, send data, or mutate production merely to73 test the CLI. Use read-only checks unless the user's task authorizes the74 business change.7576## Verify and report7778Treat a nonzero exit status as failure and parse the single JSON result. After a79mutation, perform the narrowest read-back that proves the intended state.80Report operation IDs, resource IDs/versions, output paths, and URL visibility;81never report secrets.8283For HTML, distinguish the authenticated `privateUrl` from the time-limited84public `publicUrl`. Do not describe `privateUrl` as uploader-only: any signed-in85user with `documents.read` may view it.
mmkkkkzz