flowleap-cli
AGENTS.md1 starsChanged 4 months agoMITView on GitHub
flowleap is a Rust CLI for the FlowLeap Patent AI backend API. It provides patent search, EPO OPS and USPTO document reads, citation search, academic/NPL literature search, analytics and OCR — designed for both human users and AI agents. Every one of those runs on the backend's /v1/tools facade; queries are written by the caller, locally. All four must pass before submitting changes. Gotcha: skills/ content is embedded via include_dir!, which does NOT trigger recompilation when only SKILL.md files change…
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository34 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- flowleap-academicSkill
- flowleap-authSkill
- flowleap-citationSkill
- flowleap-keysSkill
- flowleap-legalSkill
- flowleap-nplSkill
- flowleap-opsSkill
- flowleap-patentSkill
- flowleap-patstat-graphSkill
- flowleap-patstatSkill
- flowleap-sharedSkill
- flowleapSkill
- flowleap-toolsSkill
- flowleap-usptoSkill
- persona-ip-analystSkill
- persona-patent-attorneySkill
- persona-researcherSkill
- persona-startup-founderSkill
- recipe-academic-literature-reviewSkill
- recipe-audit-reportSkill
- recipe-claim-analysisSkill
- recipe-claim-draftingSkill
- recipe-custom-dashboardSkill
- recipe-find-betterSkill
- recipe-freedom-to-operateSkill
- recipe-infringement-chartingSkill
- recipe-invalidity-analysisSkill
- recipe-invention-disclosureSkill
- recipe-maintenance-feesSkill
- recipe-office-action-responseSkill
- recipe-patent-landscapeSkill
- recipe-patent-to-reportSkill
- recipe-prior-art-searchSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
13 rules. About 1 is common, 2 are distinctive, and 10 are very specific to this project.
≈1
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
All four must pass before submitting changes.
- Very specific: line 55
All commands support --output json|table|human, --dry-run, and --verbose.
- Very specific: line 56
Use --dry-run-redacted with --dry-run when request bodies may contain unpublished inventions, claims, document text, URLs, or search …
- Very specific: line 65
Every authenticated request sends Authorization: Bearer <credential> — the backend has no X-API-Key path.
- Very specific: line 129
Agent protocol: when a command fails because keys are missing or rejected, the JSON error envelope carries a providerKeysHint object with …
- Very specific: line 133
Do NOT retry or invent keys — surface the hint and ask the user to run flowleap setup (or provide keys via env/flags).
- Very specific: line 169
Every run exits with a documented code, so agents can branch on $?
- Very specific: line 211
Only these run outside the facade: key validation (usable before subscribing), auth/OAuth, and api request (the raw escape hatch, which …
- Distinctive: line 293
Every tool answers one envelope:
- Common: line 322
Never output stored credentials (API keys, tokens) in logs or verbose mode
- Very specific: line 323
Use --dry-run for safety when testing mutating operations
- Very specific: line 324
Use --dry-run-redacted when dry-run output itself may enter terminal, CI, or agent logs.
- Very specific: line 326
Search queries are written by the caller, locally — there is no server-side query builder, so an unpublished invention description never …
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
FlowLeap CLI — Agent & Contributor Guide
Overview
flowleap is a Rust CLI for the FlowLeap Patent AI backend API. It provides patent search, EPO OPS and USPTO document reads, citation search, academic/NPL literature search, analytics and OCR — designed for both human users and AI agents. Every one of those runs on the backend's /v1/tools facade; queries are written by the caller, locally.
Build & Test
cargo build # Build the binary
cargo test # Run all tests
cargo clippy # Lint (must pass with zero warnings)
cargo fmt --check # Format checkAll four must pass before submitting changes.
Gotcha: skills/ content is embedded via include_dir!, which does NOT
trigger recompilation when only SKILL.md files change — a skills-only edit
tests against a stale embed. touch src/commands/skills.rs (then rebuild)
before trusting skills install output or regenerating goldens.
Architecture
| File | Purpose |
src/main.rs | CLI entry point, clap argument parsing, command routing |
src/config.rs | TOML config (config.toml) and credentials (credentials.toml) management |
src/client.rs | HTTP client context — auth injection, request building, dry-run/verbose |
src/output.rs | Output module (re-exports formatter) |
src/output/formatter.rs | JSON, table, and human-readable output formatting |
src/commands/auth.rs | OAuth device flow, personal API tokens (create/list/revoke), status |
src/commands/tools.rs | Agent-first tool facade: list/describe/run /v1/tools/*, plus call_tool_data — the shared seam every data command runs on (unwraps the tool envelope to its data payload). The exception: the patstat commands call call_tool_envelope so their typed errors come back unprinted and render their own way; both paths share unwrap_tool_result and retry_policy_for |
src/commands/mcp.rs | flowleap mcp stdio bridge: tools/list mirrors the /v1/tools registry verbatim and tools/call runs a tool (one compact-JSON text block; for get_patent_image with include_images each PNG/JPEG page leaves the JSON and arrives as a Page N of <docId> text block plus an MCP image block, the same shape the hosted MCP server emits — mcp_content); it also serves the PATSTAT doctrine read at startup through the patstat_docs tool as six resources (flowleap://patstat/semantic-model, its index …/semantic-model/index, …/examples, …/workflow/{portfolio-analysis,guarded-sql,graph}) and three prompts (patstat-<workflow>, a plain text rendering of the served workflow), plus one resource template, flowleap://patstat/semantic-model/view/{name}, read on demand through the same tool and cached per process (an unknown view is -32602 listing the available views). It authors no tool and no doctrine; a document that fails to load is logged to stderr and skipped. --check reports tool, resource, template and prompt counts |
src/commands/skills.rs | Embedded agent-skill installer (skills/ baked into binary): multi-harness targets (claude/claude-project/codex/cursor/gemini/--dir), version stamps, skills update |
src/commands/patent.rs | EPO patent search (caller-written CQL) |
src/commands/examiner_baseline.rs | patent examiner-baseline: the Examiner Baseline (agent-v2 ADR 0010). Calls the backend examiner_baseline tool when the registry lists it; otherwise walks the family itself (reads every member publication's citedReferences and a US grant's enriched office-action citations). Either way it prints one cited-document × office matrix with gap rows; --verbose names the path. No model call; --json prints the Baseline shape the human table is derived from, and a cell names each category's own claims when the search report pairs them (categoryClaims) |
src/commands/uspto.rs | USPTO ODP search, grants, applications, continuity, file wrapper (transactions/assignments/foreign-priority/adjustment/attorney/documents + OCR document text) |
src/commands/ops.rs | EPO OPS document reads (biblio, claims, description, family, legal, abstract), EP Register reads and the EP Register search (register-search, the one search with a representative index) |
src/commands/academic.rs | Academic literature search |
src/commands/npl.rs | Non-patent literature search (OpenAlex) and npl-work, one cited paper to its OpenAlex record |
src/commands/citation.rs | USPTO enriched citation search |
src/commands/api.rs | Profile/usage + raw API escape hatch |
src/commands/health.rs / doctor.rs | Health probes and environment diagnosis |
src/commands/config_cmd.rs | CLI configuration management |
src/commands/upgrade.rs | Channel-aware self-update (upgrade/update): detects npm/raw-binary/cargo from the running binary's canonical path (a Homebrew branch exists but no tap is published — never advertise it); raw binaries self-update with sha256-verified atomic swap and then refresh installed skills by invoking the NEW binary (refreshing in-process would rewrite the old content); --check reports {channel, currentVersion, latestVersion, updateAvailable, command} with no side effects |
src/update.rs | Once-a-day update notice (recommends flowleap upgrade) + cached_latest() seam consumed by doctor |
Command Structure
flowleap <command> <subcommand> [flags]All commands support --output json|table|human, --dry-run, and --verbose.
Use --dry-run-redacted with --dry-run when request bodies may contain
unpublished inventions, claims, document text, URLs, or search queries.
Config Precedence
CLI flags > environment variables > ~/.config/flowleap/config.toml
Authentication
Every authenticated request sends Authorization: Bearer <credential> — the
backend has no X-API-Key path. The credential is either a Clerk JWT (from
the OAuth device flow) or a long-lived personal API token (fl_pat_…).
Credential sources (checked in order):
--tokenflag orFLOWLEAP_TOKENenv var--api-keyflag orFLOWLEAP_API_KEYenv var (use anfl_pat_…token here)- Stored credentials in
~/.config/flowleap/credentials.toml(written 0600)
Token lifecycle: flowleap auth login (OAuth) → flowleap auth create-token
--name <n> [--store] → flowleap auth tokens / flowleap auth revoke-token <id>.
API tokens cannot mint further tokens (backend-enforced).
flowleap auth status verifies the credential (it probes /api/profile),
so it reports whether the credential works, not merely that one is stored:
verification.state is valid (exit 0), rejected — present but refused with
a 401 (exit 3), absent (exit 3), or unverified when the check could not be
completed (exit 7; --dry-run keeps exit 0). Read verification.checked before
trusting a state: an unreachable backend yields unverified, never rejected,
because the absence of a verdict is not evidence against the credential.
All /v1/* patent-data routes additionally require an active plan — every
new account starts a free 7-day trial period at sign-up (backend ADR 0018), and
after it a 402 subscription_required with an upgradeUrl answers — and share a fixed
60 requests/minute/user rate limit (429 + Retry-After, surfaced as
retryAfterSeconds in JSON error envelopes).
Store-time TTL guard — every path that persists an OAuth session token
(auth login, --json auth login, flowleap setup) decodes its exp claim
before writing to credentials.toml and refuses, loudly, to store one with
under 10 minutes left. This guards against flowleap-backend#254: device-flow
approval has, on occasion, echoed back a short-lived default Clerk session
token instead of the long-lived flowleap-template token the server is
supposed to mint — storing it would silently shadow a still-good fl_pat_…
token with a credential dead before the next command runs. The refusal exits
3 (auth required) and names the actual lifetime found; re-run flowleap auth
login. Tokens that aren't a decodable JWT (an fl_pat_… token, for example)
are stored as before — the guard only fires on a positively short exp.
Patent-Data Keys (BYOK)
Patent data may require the user's own provider credentials — EPO OPS
(consumer key + secret, a pair) and USPTO ODP (API key). The domain term is
patent-data keys; provider_keys_required / provider_keys_invalid /
trial_budget_exhausted are the wire codes. The CLI stores them in
credentials.toml (0600) and forwards them per-request as
x-epo-ops-key/x-epo-ops-secret/x-uspto-odp-key headers; they are never
logged (verbose/dry-run output redacts them). That is a forwarded key. A
stored key is one the human added on the FlowLeap "Patent-data keys" page
(https://www.flowleap.co/en/dashboard/keys, backend ADR 0023); the backend uses
it when no forwarded key is present. keys test reports the key in use per
office as source user (forwarded) | stored | server | none, and
doctor counts stored as a key present (no key next step) and shows the
source in keyValidation.providers.
flowleap setup/flowleap keys setup— interactive wizard (human-only: keys come from browser signups; refuses to run without a TTY)flowleap keys set epo --key <k> --secret <s>/keys set uspto --key <k>— non-interactive; validates live before saving (--no-verifyto skip)flowleap keys list(masked; aliaskeys status) /keys test(live verdicts viaPOST /v1/keys/validate, exit 9 when a provider is invalid or missing) /keys rm <provider>- Env overrides:
FLOWLEAP_EPO_KEY,FLOWLEAP_EPO_SECRET,FLOWLEAP_USPTO_KEY
Agent protocol: when a command fails because keys are missing or rejected,
the JSON error envelope carries a providerKeysHint object with
code (provider_keys_required | provider_keys_invalid |
trial_budget_exhausted), provider, and requiresHumanIntervention: true.
Do NOT retry or invent keys — surface the hint and ask the user to run
flowleap setup (or provide keys via env/flags). While the backend keeps
stored keys, a data_keys_required hint (and a patent_provider_key_invalid
hint when the rejected key is the stored key, backend #518) also carries
keysPageUrl and a nextStep ({ id: store-epo-keys | store-uspto-key, actor:
"human", title, url }, copied verbatim from the error body, backend #516);
relay that page link, and never ask for the key value in the chat. The
trial_budget_exhausted hint never takes them. The trial_budget_exhausted
variant (backend ADR 0017: today's shared trial data budget is spent, 429) also
carries resetsAt — it lifts on its own at the next UTC day, and the user's own
free keys lift it permanently. Human/table output renders the same hint as an
info box on stderr.
The hint is raised from backend error codes only — data_keys_required,
patent_provider_key_invalid and trial_data_budget_exhausted (each carrying
a structured provider field), and the ODP-specific odp_api_key_missing. Error message text is never inspected:
backend wording is freely editable by policy, so a reword must not be able to
invent or erase a key gate. An error that merely mentions EPO_CLIENT_ID in its
message is not a gate.
Key-gate doctrine — authored in the flowleap-keys skill, mirrored from the
app's shipped prompt so both harnesses have one personality. A
provider_keys_required gate is a user-action stop for that office, never an
exhausted route: no web-scraped substitute for it (searches or single-document
reads), and the free key is never framed as a paywall. A gate is read, never
inferred — only that explicit code means gated, so empty results, truncated
payloads, and 5xx keep the normal fallbacks. With the other office live, deliver
its results in full, name the gap as a missing-key gap, ask once at the end, and
never silently narrow a prior-art or FTO scope. Keyless commands (patstat,
academic, npl) may be offered as different data, never as a
substitute. After the key lands, re-run only the gated office and merge. Keep
this wording aligned with the app prompt when either side changes
(abdullahatrash/flowleap-agent-v2#173).
Exit Codes & Structured Hints (agent integration)
Every run exits with a documented code, so agents can branch on $? without
parsing JSON:
| Code | Meaning | Trigger |
| 0 | Success | |
| 1 | Generic failure | Any error without a dedicated code (config, response parsing, other 4xx/5xx) |
| 2 | Usage error | clap argument/flag parse failure |
| 3 | Auth required | HTTP 401, or the local require_auth guard finding no credential at all (typed AuthRequiredError; the --json envelope carries error.code: "unauthenticated") |
| 4 | Subscription required | HTTP 402 — a human must subscribe; see subscriptionHint |
| 5 | Not found | HTTP 404 |
| 6 | Rate limited | HTTP 429 — back off, then retry; see rateLimitHint |
| 7 | Network failure | Connection failure or request timeout reaching the backend |
| 8 | Endpoint gone | HTTP 410 endpoint_gone — this CLI build calls a retired endpoint. Run flowleap upgrade; see endpointGoneHint for the successor |
| 9 | Patent-data keys | provider_keys_required / provider_keys_invalid / trial_budget_exhausted. Raised wherever a providerKeysHint lands on the envelope (the backend answers 400 — or 429 for the trial budget — which would otherwise map elsewhere), and by keys test / keys set on a rejected or missing key. A human must add keys; never retry (the budget variant alone also lifts at its resetsAt) |
On failure the JSON error envelope may carry structured hints — additive fields only, so existing envelope consumers are unaffected. Human/table output renders each hint as an info box on stderr:
providerKeysHint— missing/rejected EPO or USPTO keys (see Provider Keys above). Needs a human; do not retry.subscriptionHint(402) —{ requiresHumanIntervention: true, upgradeUrl, message }(no plan name — there is one flat License). The upgrade URL comes from the response body when present, elsehttps://flowleap.co/pricing. Subscribing happens in a browser — surface the URL to the user; do not retry.rateLimitHint(429) —{ retryAfterSeconds?, message }. WhenretryAfterSecondsis present (from theRetry-Afterheader, also surfaced top-level on the envelope), wait exactly that long before retrying.endpointGoneHint(410) —{ code: "endpoint_gone", requiresUpgrade: true, successor?, reason?, serverMessage?, message }. The build is stale: the endpoint is retired for good. Upgrade the CLI; never retry the same call.
API Endpoints
The /v1/tools/* facade is the only patent-data surface. Every data
command — patent, ops, uspto, citation, npl, academic,
analytics, ocr, and the ergonomic verbs — POSTs to /v1/tools/<name>; the
provider-specific routes they used to call are retired (backend ADR 0013).
flowleap tools list discovers every tool with its JSON input schema and
per-tool docs; flowleap tools run <name> executes one.
Only these run outside the facade: key validation (usable before
subscribing), auth/OAuth, and api request (the raw escape hatch, which calls
whatever path you give it). Every patstat command — portfolio, docs,
query and the graph verbs — runs on the facade like every other data
command. The backend still serves the /v1/patstat/* routes; the CLI no
longer calls them.
| Endpoint | Method | Auth Required |
/oauth/device | POST | No |
/oauth/device/token | POST | No |
/health (liveness) | GET | No |
/v1/health (readiness — carries apiVersion) | GET | No |
/v1/tools | GET | Yes |
/v1/tools/openapi.json | GET | Yes |
/v1/tools/{tool_name} | POST | Yes |
/v1/patstat/* | POST/GET | Served by the backend; not called by the CLI (every patstat command runs on the tools facade, #95/#96) |
/api/profile | GET | Yes |
/api/usage | GET | Yes |
/api/tokens (create/list) | POST/GET | Yes (create requires Clerk auth, not an API token) |
/api/tokens/{id} | DELETE | Yes |
/v1/keys/validate | POST | Yes (no subscription required) |
Which tool each command calls
| Command | Tool |
patent search, ops search | search_patents (provider: epo_ops) |
uspto search | search_patents (provider: uspto) |
ops biblio / abstract / claims / description / legal | get_bibliography / get_abstract / get_claims / get_description / get_legal_status (biblio --designated-states → include_designated_states, --resolve-npl → resolve_npl; both opt-in, each costs extra reads) |
ops register-biblio | get_register_biblio (EP Register: representatives of record, opponents) |
ops register-search | search_register (--cql → query, --start/--end → range: "start-end"). EP Register CQL, EP applications only — the one search with a representative index: re (professional representative), op (opponent), ia (inventor or applicant); pa, in, ti, pn, ap, pr, pd, ic work too. nm is a name in any role (applicant, inventor, representative, opponent): use it when a role index returns 0 to find which role the person holds; the register stores names surname-first, so use the surname alone or nm="Surname, First". A zero-result role-index query can carry a top-level hint string, printed as Hint: <text> after the Total line in human/table output (verbatim in --json). ag, rep, ab, cpc, st, ps, fd, ctr are not register indexes (get_search_syntax provider: epo_register lists both sets). total counts the whole query, capped at 10000; one row per EP application, docId null while none is published. search_patents has no representative index at any office |
ops family | get_family — the INPADOC extended family. get_patent_family is the narrower simple-family equivalents tool |
uspto grant / application / continuity | get_us_grant / get_us_application / get_continuity |
uspto transactions / assignments / foreign-priority / adjustment / attorney | get_transactions / get_assignments / get_foreign_priority / get_patent_term_adjustment / get_attorney |
uspto documents / document-text | get_application_documents / read_application_document |
citation search / forward / stats | search_office_action_citations / search_enriched_citations / get_citation_stats |
citation novelty | search_office_action_citations with category: "X", examiner_cited_only: true — a recipe, not a tool of its own |
patent examiner-baseline | examiner_baseline (publication), after a GET /v1/tools check. When the registry does not list it (older backend), the fallback walk: get_family, then get_bibliography per member publication, get_us_grant per US grant (resolves the application number) and search_office_action_citations (size: 1000) per resolved application. A per-document failure becomes a gap row; a key gate, 401/403, 402, 429 or 410 stops the verb with its usual exit code |
academic search, npl | search_academic / search_npl (human output names a failed search_academic source on stderr) |
npl-work | get_npl_work (<reference> → reference) |
analytics, ocr | patent_analytics / ocr |
compare / figures / summary / timeline / convert-number | compare_patents / get_patent_image / get_patent_summary / get_prosecution_timeline / convert_patent_number |
patstat portfolio | patstat_portfolio (--from-year/--to-year → from_year/to_year; sends offices: "all" by default so every office stays in the table, --offices top sends the tool default top, #107) |
patstat docs | patstat_docs (--section/--workflow/--endpoint; --part index or --view <name> only with --section semantic-model, sent as part/view; no flag sends compact: false for the full docs, --compact sends compact: true). flowleap mcp loads its six doctrine resources and its view template through this tool too (free at sign-in, backend ADR 0021) |
patstat query | patstat_query (--retry-of → retry_of) — never resent by the client, see below |
patstat graph resolve | patstat_resolve (<query> → q) |
patstat graph cpc | patstat_cpc (<query> → q) |
patstat graph patent | patstat_patent (<publication> → number) |
patstat graph applicant | patstat_applicant (<psn_id> → psn_id, a number) |
patstat graph technology | patstat_technology (<cpc> → cpc) |
patstat graph neighborhood | patstat_neighborhood (--depth → depth, --edge-types a,b → edge_types: ["a","b"], --token-budget → token_budget) |
patstat graph path | patstat_path (<a> <b> → a/b, --max-hops → max_hops, --token-budget → token_budget) |
patstat graph explain | patstat_explain (--token-budget → token_budget) |
No hidden retry on guarded SQL. The client resends a request on its own
after a 5xx, a connection failure or a short 429 (twice by default,
FLOWLEAP_MAX_RETRIES). patstat_query is the one exception: it is sent
exactly once, on patstat query, tools run and the MCP tools/call path
alike (tools::retry_policy_for, the one place the policy is chosen). Backend
ADR 0010 gives the agent the one informed retry; a client resend would swallow
the cold-timeout signal. Its typed errors (patstat_sql_*, patstat_busy, …)
reach the caller with the backend code, message and details verbatim.
Breaking for --json consumers (next release). The three patstat
commands print the tool data verbatim. portfolio and query lose the
top-level success and gain attribution. docs prints the tool data
itself, so the semantic model is .yaml, not .data.yaml. Typed errors carry
their extra fields under error.details (for example
error.details.candidates on patstat_applicant_ambiguous). The tool inputs
are from_year, to_year and retry_of. The patstat graph verbs (#96)
follow the same rule: every result loses the top-level success;
resolve, neighborhood, path and explain gain top-level data_edition
and attribution (the new cpc carries both at the top level too); and the graph patent 422 carries its candidates at
error.details.candidates.
Tool parameters are snake_case. figures --out fetches image bytes from
get_patent_image itself (include_images: true returns base64 pages) — there
is no separate byte-fetching endpoint. Through MCP (stdio bridge and hosted
server alike) those pages arrive as image content blocks, not as base64
inside the text block.
Every tool answers one envelope:
{ "success": true, "tool": "get_bibliography", "data": { /* tool-specific */ }, "executionTimeMs": 432, "cached": false }Commands unwrap it and print data; cached is present only when the backend
could determine it. On failure:
{ "success": false, "error": { "code": "NOT_FOUND", "message": "..." }, "status": 404 }Branch on error.code, never on message. Codes come from a closed
registry and never change once shipped; message wording is freely editable by
backend policy. Facade codes: INVALID_INPUT (422, carries issues),
UNKNOWN_TOOL (404), TOOL_EXECUTION_ERROR (422), NOT_FOUND (404),
RATE_LIMITED (429), INTERNAL_ERROR (500). Access codes:
subscription_required (402), data_keys_required / patent_provider_key_invalid
(400, each carrying provider), trial_data_budget_exhausted (429, carries
provider, remaining: 0, resets_at — backend ADR 0017),
rate_limit_exceeded (429), endpoint_gone (410, carrying successor and
reason). Success envelopes may carry warnings[] — trial_data_budget_low
(with remaining, resets_at) means today's shared trial budget is ≥80% spent.
Live OpenAPI spec, generated from the registry: <base-url>/v1/tools/openapi.json.
Security
- Never output stored credentials (API keys, tokens) in logs or verbose mode
- Use
--dry-runfor safety when testing mutating operations - Use
--dry-run-redactedwhen dry-run output itself may enter terminal, CI, or agent logs. It preserves request shape while replacing sensitive values. - Search queries are written by the caller, locally — there is no server-side
query builder, so an unpublished invention description never has to leave
the machine to become a query (see the
flowleap-patentskill). - Authorization header is stripped from verbose output
- Base-URL credential guard: when the effective base URL's host is not
flowleap.co/*.flowleap.co/localhost/127.0.0.1/::1, the CLI prints one stderr warning per invocation naming the host and the credential kinds that will be sent (presence only, never values). In an interactive terminal it requires y/N confirmation before the first request;--yes(orFLOWLEAP_ASSUME_YES=1) skips the prompt. Non-TTY,--json, and--dry-runruns warn and proceed, so agents are never blocked and stdout stays clean.
Skills
The skills/ directory contains SKILL.md files for AI agent consumption. Each skill describes one CLI capability with usage examples, flags, and expected output. Skills are organized into:
- Service skills (
flowleap-*): One per CLI command - Persona skills (
persona-*): Role-based bundles for specific workflows - Recipe skills (
recipe-*): Multi-step workflow templates
Skills vs. tools (when to write which)
Skills instruct, tools reach. A skill can only orchestrate data that some existing backend tool/command already touches. Default every new capability to a skill; add a backend tool only when the data is unreachable — and then add the thin passthrough first and put the workflow in a skill on top of it.
- Author CLI-canonical first. New capability-skills are written here (the
CLI dialect), then ported to the VS Code app's skill dialect
(
flowleap-agent-v2 …/assets/skills/, extension tool names,user-invocable) in the same sitting. The two ecosystems do not sync; seeCONTEXT.mdfor the vocabulary. - Never route around a missing tool. A skill must not instruct agents to call provider APIs (EPO/USPTO) directly with the user's BYOK keys — that forfeits caching, key handling, rate-limit protection, and uniform error envelopes. Missing data is the signal to add the thin tool, not to hand-roll HTTP in a skill.
- MCP resources and prompts are served doctrine, not skills.
flowleap mcpmirrors them from the backend (the PATSTAT doctrine, throughpatstat_docs). Change them in the backend; a skill points atflowleap patstat docsinstead of copying them. - Chat clients route to tools. claude.ai, ChatGPT and Cowork reach
FlowLeap through the hosted MCP server connector and have no shell. The
command-to-tool table lives in
flowleap-shared("Chat clients with the FlowLeap connector"), the one-call verb table inflowleap, and every other skill that invokesflowleap …carries the one-line routing sentence near its top.tests/skills_connector_test.rschecks the table names against the vendored registry listtests/support/registry-tools.txt(refresh it with the command in its header when the registry changes) and checks that every command-invoking skill has the sentence. A new command-invoking skill needs the sentence; a new command needs its row. - Office coverage lives in one section. The office coverage of the text
tools, the family-member workaround with its shares and limits, and the
served failure (
FULLTEXT_UNAVAILABLE,error.details.reasonno_sourcewith theworkaroundfield,not_configuredwithout) live in theflowleap-sharedsection "Office coverage of the text tools and the family-member workaround". Every other skill points there; a short restatement of the offices is allowed only wheretests/skills_office_coverage_test.rschecks it against the vendored blocktests/support/office-coverage.json(refresh it with the command in that test's header whenserver_infochanges). - Distribution is release-gated. CLI skills ship inside the binary (next
tag) and reach the website marketplace via the
flowleap-pluginsre-sync (bumpsync.jsonref, add the entry, copy byte-for-byte). Budget the re-sync into every release that touchesskills/.
Environment Variables
| Variable | Description |
FLOWLEAP_API_KEY | API key for authentication |
FLOWLEAP_TOKEN | Bearer token for authentication |
FLOWLEAP_BASE_URL | API base URL override |
FLOWLEAP_ASSUME_YES | Skip confirmation prompts (same as --yes) |
Testing
- Unit tests: config parsing, credential storage, output formatting
- Integration tests: in
tests/directory - Test with
cargo test
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

