Imported from jentic/jentic-one (skills/jentic/SKILL.md). Install upstream with npx skills add jentic/jentic-one --skill jentic. Copyright stays with the author.

name: jentic description: Use this skill whenever the user wants to work with a third-party or external API/tool through the Jentic platform — e.g. asks to "find the vessel-tracking API and add it", "get rows from this Google Sheet", connect Slack, import/search/discover an API, integrate or automate a SaaS, pull data from a service, or call an external endpoint. Prefer launching this before ToolSearch or hand-rolled HTTP: it drives the audited Jentic CLI loop (identity → discover → request access → execute), even inside a code repo. Do NOT use it for local-only work (editing code, finding files, adding a package/dependency, or questions with no external API call). version: 1

Using Jentic from the CLI

Jentic is an API broker: you discover operations across many APIs, then execute them through a single authenticated gateway without managing each API's credentials yourself. The jentic CLI is the agent-facing entrypoint.

The same loop is also exposed over MCP by the local jentic mcp stdio server — available in the jentic CLI from the next release; check jentic mcp --help. If your session has jentic MCP tools, prefer them; use the CLI for setup/access recovery and anything not exposed over MCP. Both surfaces talk to the same instance — check backend/host in the identity stamp on MCP tool results if in doubt.

When to Use

• You need to call a third-party API (Stripe, GitHub, Slack, …) but don't have its SDK or credentials wired up.
• The user asks to find, add, import, connect, or search for an API/tool ("find the vessel-tracking API and add it", "get rows from this Google Sheet") — treat these as Jentic tasks, not local-repo or generic tool-search tasks, even when you are running inside a code repository.
• You want to discover what operations exist for a capability ("create a payment", "list pull requests") instead of reading raw OpenAPI specs.
• You are an agent that should drive real API calls through one audited broker.

Reach for this skill's jentic CLI before generic tool discovery (ToolSearch) or hand-rolling HTTP calls: the broker is the single audited path to external APIs and handles credentials for you.

Prerequisites

• The jentic CLI is installed and on PATH.
• A reachable Jentic control plane. The base URL comes from the active context's environment — set it with jentic env add <name> --url <URL> and select it with jentic context use <name> (inspect via jentic context view). Onboard a fresh machine with jentic register --url <URL>. There is no --base-url flag on data-plane commands.
• Remote deployments: if the environment's base URL is remote (an https://… host in jentic context view), the broker must be set explicitly too — broker_url on the environment (pass --broker-url to register, or jentic env add), or JENTIC_BROKER_URL in file-less mode. It is never derived from the control-plane URL. A loopback install seeds it automatically.

Procedure

1. Confirm you have a valid identity

You normally don't set up your own identity — your human operator runs jentic register (or jentic setup) out-of-band, which connects this machine to a Jentic install, registers this agent, waits for a human to approve it, and (for setup) writes this skill. First, check your setup:

jentic doctor

If the Identity section passes (a registered identity and a usable token or API key), skip to step 2. If it does not (no context, "not registered", or "pending"), stop and ask your operator to run jentic register --url <install URL> and approve the agent — that step blocks on a human and cannot be completed by an autonomous agent. (For a local install the URL must be http://127.0.0.1:8000, not localhost — the token audience is matched exactly.) Once approved, a token is minted and reused automatically; you never handle raw API credentials — the CLI attaches the bearer token for you.

If your operator self-registered this agent and handed you a one-time claim token, bind it to a human identity with jentic identity claim <agent-id> --token <token> (an agent cannot claim itself; requires an active human context).

2. Check what you can do, and request access if needed

See your own identity, status, scopes, and which toolkits you're bound to:

jentic access whoami

Each toolkit binding lists the APIs it serves (serves: [{vendor, name, version}]). This tells you exactly what you can already call. Combined with the catalog (what's available to add — see step 3), it's your map of the workspace.

Decide access from whoami first — do NOT execute an operation just to see whether you have access. A denied execute is a wasted round-trip; you can tell in advance:

• If a binding already serves the API you need → you have access. Skip straight to inspect/execute; file no request.
• If nothing you're bound to serves it → you do not have access yet. Provision it before your first execute — do not "try execute and branch on the denial":

jentic access request --provision <vendor/name> \
  --auth <bearer|api_key|basic|oauth2|none> \
  --rules-json '[{"effect":"allow","methods":["GET"],"path":".*"}]' \
  --reason "why you need this — shown to the human who approves it" \
  --wait

--wait blocks until a human fulfils and approves the plan in the dashboard; once approved, the toolkit binding is live immediately — just retry execute. Always pass --reason on every access request (--provision, --toolkit, or --scope): a human reviews it before approving and your reason is shown to them — a clear one-liner ("fetch the user's open PRs to summarise them") is what gets you approved faster. You normally do not need jentic access refresh after a --provision plan: bindings take effect live, and a plan grants no new token scope. Only refresh after an approved scope:grant and only if whoami flags the scope as not yet on your token (see the stale-scope note it prints).

File once, richly — never thrash. Work out the full access end-state up front — from whoami, the catalog, and the task — and file it as one composite request: every target flag repeats and combines, so a job needing several APIs is one command the human decides in one sitting:

jentic access request \
  --provision slack.com/api --auth slack.com/api=bearer \
  --rules-json 'slack.com/api=[{"effect":"allow","methods":["POST"],"path":"/chat\\.postMessage"}]' \
  --provision googleapis.com/sheets --auth googleapis.com/sheets=oauth2 \
  --rules-json 'googleapis.com/sheets=[{"effect":"allow","methods":["GET"],"path":".*"}]' \
  --toolkit github.com/api \
  --reason "one reason covering the whole job" \
  --wait

Each --provision adds a full plan for that API — keep every plan complete (auth, rules, reason), exactly as you would for a single one; --toolkit/--toolkit-id/--scope add single items. With more than one --provision, key --auth and --rules-json by the same vendor/name[/version] you passed to --provision (include the version in the key if you used one); the bare form applies when there is exactly one. Never file duplicate or per-operation requests, and don't withdraw-and-refile to tweak a proposal; once filed, tell your operator an approval is waiting and hand back (or --wait). If a composite collides with an older pending request for one of its targets, nothing is filed — drop that target or jentic access withdraw the old request, then re-file. --wait can end partially_approved (exit 4): check jentic access status <id> to see which items were granted before proceeding.

If you'd rather be reactive, the broker also guides you: when execute is denied it prints a recovery line on stderr (the agent_directive) and exits 2, so you can branch on the exit code instead of mistaking the 4xx body for success. The directive tells you exactly how to recover — which differs by denial:

• no_toolkit_binding (403) — nothing serves this API yet (no toolkit, and usually no credential). File a provisioning plan describing the whole path to first execution, and propose the auth type and permission rules you read from the API spec:

jentic access request --provision stripe.com/api \
  --auth bearer \
  --rules-json '[{"effect":"allow","methods":["GET"],"path":".*"}]' \
  --reason "why you need this — shown to the human who approves it" \
  --wait

• toolkit_serves_api: false — no toolkit serves this API yet, so a bare --toolkit binding request would be denied ("No toolkit serves API …"). Filing it now is a dead-end. File the --provision plan above instead: it describes the whole path (create toolkit, provision + bind a credential with your proposed rules, bind you), which a human fulfils and approves in the dashboard. The directive's suggested_command already points at --provision in this case. The plan does not force a new toolkit: during fulfilment the operator can add the credential to a toolkit they already have (the wizard offers both) — worth relaying when your operator mentions an existing toolkit they want to extend.

• toolkit_serves_api: true — a toolkit already serves this API and you just aren't bound to it; the directive suggests jentic access request --toolkit <vendor/name> --wait. File that and wait for approval.

• credential_not_provisioned (424) — you're bound to a toolkit, but no credential (account) is connected. Filing an access request will not fix this; the directive carries a provisioning_url — hand it to your operator to connect the account, then retry.

• credential_undecryptable (424) — a credential is connected, but its stored secret can no longer be decrypted (typically the deployment's encryption key rotated underneath it, e.g. a reinstall over existing data). Neither an access request nor retrying will fix this — ask your operator to remove and re-add the credential, then retry.

• credential_identity_mismatch (403) — a toolkit is bound and a credential is connected, but that credential's stored identity doesn't cover this API (e.g. it targets a different name/version, or was stored in a non-canonical form). Filing an access request will not fix this — the binding already exists. The directive's parameters.expected vs parameters.found name the mismatch; if parameters.would_match_if_normalized is true the credential just needs re-provisioning to canonicalize its identity. Either way, ask your operator to fix or re-provision the credential so it targets expected, then retry.

• ambiguous_toolkit (409) — multiple toolkits you're bound to serve this API. The directive lists candidates; resend the same execute with --header Jentic-Toolkit-Id=<toolkit_id> (the directive also gives a copy-pasteable suggested_command).

Always follow the agent_directive's suggested_command / provisioning_url rather than assuming which recovery applies. You can also request access proactively before you're denied.

Proposing permission rules from the spec

--provision is your chance to propose the credential's auth type and its permission rules as a first pass — a human reviews and edits them before approving. Do the work up front:

1. Read the operation surface and security schemes: jentic apis operations <vendor/name/version> and jentic inspect <operation_id> show methods, paths, and the declared auth.
2. Pick --auth from what the spec declares (bearer, api_key, basic, oauth2), or none if the API needs no credential.
3. Translate the user's plain-English intent into rules. "Read everything, write only to the prod board" becomes concrete allow/deny rules with methods/path, e.g. [{"effect":"allow","methods":["GET"],"path":".*"}, {"effect":"allow","methods":["POST","PUT"],"path":"/boards/prod/.*"}]. An allow rule must constrain at least one of methods/path/operations. Be honest at the enforcement seam. The broker matches a rule against the request's HTTP method, URL path, and OpenAPI operation id — never the request body. An intent that hinges on a body field ("only allow messages to the #general channel" when the channel is a POST-body field) cannot be enforced by these rules. Don't propose a rule that silently won't fire — say so, and offer the real choices: allow the operation broadly (the human accepts the wider grant), deny the operation entirely, or allow it and record the constraint as instructions you follow yourself (unenforced). Also sanity-check your proposal before filing: rules evaluate first-match-wins, so an early broad allow shadows every rule after it, and a rule set that contradicts the intent you stated in --reason will confuse the human reviewing it.
4. You never enter the credential secret and you never approve — the human fills the secret in the dashboard and grants the plan. You propose; they decide.

A plain toolkit:bind (--toolkit) is only the last mile — use it when a toolkit for the API already exists (e.g. an operator created one) and you just need to be bound to it. When nothing serves the API yet, --provision is the right first move; a bare --toolkit would auto-deny.

--toolkit/--provision take a vendor/name[/version] reference (the broker also suggests the exact command in its agent_directive). --wait blocks until a human decides and sets the exit code: 0 = approved, 2 = denied — read the item's decision_reason (in the JSON, or shown under the item on a TTY) to learn why before giving up, 3 = still pending when --timeout elapsed (poll later with jentic access status <id>), 4 = partially approved. Without --wait you get a request id and an approve_url to hand to your operator. Granting is always a human action — you file and wait, you never approve yourself.

If you file a bare toolkit:bind (--toolkit) for an API that nothing serves yet, approval comes back denied with decision_reason: "No toolkit serves API <vendor/name>; provision and bind a credential for it first". That is the signal to file a --provision plan instead: it describes the missing toolkit, credential, rules, and binding as one request the operator can fulfil and approve in the dashboard.

Track and manage your requests:

jentic access list
jentic access status <request_id>
jentic access withdraw <request_id>

--wait's --timeout is a duration with a unit — --timeout 120s, 2m, 90s. A bare number (--timeout 120) is rejected. Once a request is approved, retry the execute that was denied.

3. Find an operation (import first, then search)

search only sees operations that have been imported into this deployment's local registry. On a fresh install the registry is empty, so search returns {"data": []} until you import something. Import before you search — if the user already named the API/vendor (e.g. "Google Sheets"), go straight to catalog search/import; don't search an empty registry first and waste a call. The discovery order is:

1. Browse the public catalog for an importable API:

jentic catalog search "spreadsheets"

2. Import the one you want into the local registry (auto-promotes to live):

jentic catalog import googleapis.com/sheets

Importing an already-cataloged API is gated on catalog:import, which an approved agent holds by default — no access request needed. Just run the import. (This is narrower than importing arbitrary URL/inline specs via POST /apis, which still needs apis:write.) If import unexpectedly fails with 403 … requires one of: catalog:import — e.g. you were approved before catalog:import became a default scope and weren't re-granted — request it, wait for a human to approve, refresh your token, then retry:

jentic access request --scope catalog:import --reason "import the Sheets API to read the user's spreadsheet" --wait
jentic access refresh
jentic catalog import googleapis.com/sheets

To register an API that is not in the catalog, upload its OpenAPI spec directly with jentic apis import <file|url> --vendor <vendor> --name <name> --version <version> (reads a local file inline or fetches a URL; async, prints a job id). This needs apis:write rather than catalog:import.

3. Now search the local registry, or list an API's operations directly:

jentic search "get values from a spreadsheet range" --limit 10
jentic apis operations googleapis-com/googleapis-com-sheets/v4

search returns JSON when piped. Each hit carries both a registry operation_id and a _links.inspect (a /inspect?id=METHOD%20URL link). Pass the operation_id straight to inspect/execute — it resolves by registry key — or use the METHOD URL pair the link decodes to. (The id shown by jentic catalog show is the spec's operationId; inspect accepts that too, via a fallback, but the operation_id from search/apis operations is the most direct.)

If search returns no results, it prints a hint to run jentic catalog search / jentic catalog import first — that almost always means nothing relevant is imported yet. Both reading the registry and importing a cataloged API need no request — an approved agent already holds apis:read and catalog:import by default, so just import and search again. Don't file an access request for a made-up "catalog read" scope.

jentic catalog outdated lists registered APIs whose upstream spec changed since import (also surfaced by jenticctl status). Re-importing promotes the new spec to live, changing behavior, so this is an operator decision: suggest the re-import (jentic catalog import <vendor/name>) to the operator and let them run it — never silently re-import on your own. (jentic catalog refresh rebuilds the catalog manifest from upstream but requires org:admin, so it too is an operator action.)

Before concluding "the data is gone", confirm which backend you're on. If APIs, credentials, or toolkits you know existed appear missing — or IDs look unfamiliar — you may be talking to a different backend than you expect. A hosted (remote) Jentic install and a local self-hosted one have independent registries and credentials, and the CLI, an agent, or an MCP server can each be bound to a different one. Check the backend your base URL serves before diagnosing data loss:

jentic context view        # shows the active context's environment + base_url
jentic api GET /instance   # reads the connected backend's identity (auth attached)

The unauthenticated /instance response reports backend (local / remote — the install's declared server.backend), canonical_base_url, host, and an opaque instance_id (null when telemetry is off). If it's not the backend you meant to use (e.g. an MCP server still on a remote backend while you imported locally), repoint that client at the right base URL rather than importing/searching again.

4. Inspect the operation's contract

Resolve an operation to its method, path, parameters, and schemas before calling it. Pass the inspect identifier from search/apis operations, or a METHOD URL pair:

jentic inspect "$(jentic search 'get spreadsheet values' --json | jq -r '.data[0].operation_id')"
jentic inspect 'GET https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values/{range}'

On a 404, inspect prints the reason and a hint on stderr and exits 2 (it is not silent). If you passed the id from catalog show and it didn't resolve, use the operation_id from search/apis operations, or the METHOD URL pair that the hit's _links.inspect decodes to.

5. Execute through the broker

Send the request through the Jentic broker. The broker is a transparent forward proxy, so the target is the full upstream URL (scheme + host + path), not a host-relative path. Reference an operation_id/inspect id from search/ inspect — the CLI fills in the upstream URL for you — or pass METHOD:URL directly.

jentic execute <operation_id> --query limit=10
jentic execute GET:https://sheets.googleapis.com/v4/spreadsheets/{id}/values/{range} --path id=ABC --path range=A1:Z10

Diagnose an execute failure by its symptom, not the exit code alone. A broker denial prints an agent_directive on stderr (exit 2). An error naming DNS, TLS, timeout, or connection refused is a transport failure — usually exit 1, but exit 2 (resolve … failed) when the operation_id lookup hits an unreachable control plane — with two causes:

Exit 2 broadly means "this request cannot succeed as asked" — a broker denial, a failed operation resolve, or missing local context (e.g. no active context configured). Don't blind-retry an exit 2: change the ask, fix the config, or request access. Exit 3 (still pending) and the transient transport failures are the retryable ones.

• Wrong target (DNS or TLS error). The broker target resolves as built-in default (https://127.0.0.1:8100) < the active environment's broker_url in ~/.config/jentic/config.yaml < flags. lookup broker.jentic.ai: no such host means the environment points at the hosted broker from a local install; a TLS error like server gave HTTP response to HTTPS client against a local target means the broker is plain http but the target resolved to https. jentic register seeds broker_url for a loopback install; otherwise set it on the environment, or override per call:

jentic register --url <control-plane URL> --broker-url <broker URL>   # fills a missing broker_url
jentic env add <env> --url http://127.0.0.1:8000 --broker-url http://127.0.0.1:8100 --force
jentic execute <operation_id> --broker-scheme http --broker-host 127.0.0.1:8100

• Missing broker on a remote install (RESOLVE_FAILED, exit 2). If the environment's base_url is remote and no broker_url is set, execute refuses up front (it never dials the local default for a remote control plane). This means the environment was onboarded without a broker: set it with jentic register --url <URL> --broker-url <broker URL> (or JENTIC_BROKER_URL in file-less mode) — ask the operator for the broker URL; do not assume a local broker.

• Stopped instance (connection refused on a local target). If the target is already local (127.0.0.1 / localhost) and the connection is refused, the target is right and the instance is probably not running (rebooted machine, Docker not started). Health-check before concluding anything: jenticctl status reports whether the control-plane server and broker are reachable. If they're down, do not retry, guess, or quietly give up — tell the user plainly, e.g. "Your Jentic One instance appears to be stopped, which is why I can't reach {API}. Restart it with jenticctl start (then jenticctl status to confirm), and I'll retry." After the restart, retry the original call and continue the task.

Quick Reference

• The authoritative command + flag reference is generated from the CLI itself, not this file: run jentic --help / jentic <command> --help (always current, works offline), or open the platform docs at /app/docs on the control plane (Reference → CLI) — the same reference rendered for humans, next to the HTTP API and Broker API references.
• jentic context view — the active context (environment + identity + base_url); start here.
• jentic access whoami — your identity, status, scopes, and toolkit bindings with the APIs each one serves (check this before executing or provisioning).
• jentic access request — ask a human for access. --provision <vendor/name> files the whole path to first execution as one plan when nothing serves the API yet; --toolkit <vendor/name> asks to be bound to an existing toolkit; --scope <scope> requests a missing scope. All target flags repeat and combine into one composite request. Always pass --reason; add --wait to block on approval (see Procedure for full examples).
• jentic access list | status <id> | withdraw <id> — track your requests.
• jentic access refresh — re-mint your token after an approved scope grant that whoami flags as not yet on your token. Bindings need no refresh — they are live on approval.
• jentic catalog search "<query>" / jentic catalog import <vendor/name> — find and import APIs (import first; search only sees imported operations).
• jentic search "<query>" → jentic inspect <operation_id> → jentic execute <operation_id | METHOD:URL> — discover, inspect, and call operations through the broker (use the full upstream URL; the broker is a forward proxy, not a path router).
• jentic register / jentic setup — operator commands that create and approve this identity (they block on human approval; not for autonomous use).
• jentic doctor — read-only self-check of THIS agent's setup (config/state dirs, resolvable identity, a usable token, control-plane reachability, clock skew). Run it first when something is off but you're not sure what; it never mints tokens or writes anything. --json for a parseable report. (This is the agent-side sibling of jenticctl doctor, which needs operator tooling.)
• jentic api <METHOD> <path> — a gh api-style authenticated passthrough to the control plane for endpoints without a dedicated command. It self-describes: jentic api ops lists available operations and jentic api describe <METHOD> <path> prints one operation's parameters, so you can discover a new route and its inputs without leaving the CLI. Pass a JSON body with -d '<json>', -d @file, or piped stdin.
• jentic history export --trace <trace_id> — export the execution history of one trace (JSON envelope with schema_version/trace_id), for auditing what you have run. --trace is required; take the id from an execute --json response or from jentic events watch.
• jentic events watch — stream live execution/approval events for this identity (long-running; Ctrl-C to stop).
• --dry-run / --export-plan — on a mutating command (execute, apis import), validate and print the request that WOULD be sent (a machine plan with --export-plan) without sending it. Use it to preview a call — including the exact broker URL and headers — before committing side effects.
• jenticctl status / jenticctl start — health-check and restart the local deployment; check this first when a local target refuses connections.
• Add --json to force machine-readable output on a terminal (works on search, execute, inspect, apis, access, doctor). context view has no --json flag — it emits JSON automatically in agent/non-TTY mode.
• Correlation & retries: export JENTIC_SESSION_ID=<your session id> and every request carries it as X-Jentic-Session-Id, so operators can group all of your calls in server logs; each execute also sends a fresh W3C traceparent. When you must retry a mutating call (POST/PUT), pass --idempotency-key <uuid> to execute — the server can then de-duplicate, and the CLI treats the request as safe for its transport-level retries.

Pitfalls

• Calling execute before the agent is registered and approved fails — there is no token. Check jentic doctor; if the Identity section warns, ask your operator to run jentic register (with --url <install URL> on a fresh machine) and approve you.
• search returning {"data": []} usually means nothing is imported yet, not that you lack access. Run jentic catalog search → jentic catalog import, then search again. Both reading the registry and importing a cataloged API need no grant — an approved agent already holds apis:read and catalog:import by default. (Importing arbitrary URL/inline specs via POST /apis is the only import path that needs apis:write.) Don't invent other "catalog read" scopes; they're rejected.
• Verify which backend you're talking to before diagnosing "missing" APIs or credentials. If your session also has Jentic MCP tools (search_apis, list_credentials, execute, …), check which backend they answer from. Tools served by the local jentic mcp server stamp backend/host on every result — compare that against this CLI's backend. Tools without the stamp (e.g. the hosted Jentic cloud platform's MCP server) may be bound to a different backend than this CLI — typically the hosted cloud workspace vs the local install. The symptom of a mismatch is silent wrong answers, not errors: an API the user just imported "doesn't exist", credentials "disappeared", or operation ids from one surface don't resolve on the other. Before concluding anything is missing or broken, check where each surface points — jentic context view shows this CLI's active environment/base_url, and jentic api GET /instance reports which backend serves it (see "confirm which backend you're on" in step 3); for MCP tools, read the identity stamp or ask your operator which backend the MCP server was configured against — and stick to one surface for the whole task.
• An execute failure is not always an access problem. A DNS or TLS error means the broker target is misconfigured (see step 5); connection refused on a local target usually means the instance is stopped — run jenticctl status, and if it's down tell the user to jenticctl start, then retry rather than abandoning the task. Only a broker denial (an agent_directive on stderr, exit 2) is an access/credential issue:
  • 403 no_toolkit_binding → check the directive's parameters.toolkit_serves_api. If true, a toolkit already serves the API and you just aren't bound — run the jentic access request --toolkit … it suggests and wait for approval. If false, nothing serves the API yet and a bare --toolkit bind would be denied ("No toolkit serves API …"); the directive suggests --provision instead — file that plan (propose --auth and --rules-json from the spec, pass --reason) and your operator fulfils it in the dashboard, into a new toolkit or one they already have — an existing toolkit never has to be recreated.
  • 424 credential_not_provisioned → the directive gives a provisioning_url for your operator to connect an account (an access request won't help).
  • 424 credential_undecryptable → the connected credential's secret can't be decrypted anymore; retrying won't help — ask your operator to remove and re-add the credential.
  • 403 credential_identity_mismatch → a bound credential exists but its identity doesn't cover this API (parameters.expected vs parameters.found). An access request won't help — ask your operator to fix or re-provision the credential so it targets expected, then retry. Follow the directive; don't keep re-sending the same execute.
• You file and wait for access; you can't approve your own requests.
• Don't execute to test access. whoami already tells you what your bindings serve; if the API you need isn't there, --provision it and wait — don't fire a execute you expect to be denied just to read the recovery directive. The directive is a fallback for surprises, not a discovery step.
• The operation_id from search/apis operations resolves directly; the id from catalog show is the spec operationId (inspect resolves it via a fallback). If one doesn't resolve, try the METHOD URL pair from the hit's _links.inspect — don't guess ids.

Verification

• jentic doctor shows a resolvable identity with a valid token.
• After jentic catalog import <vendor/name>, jentic search "<something in that API>" returns at least one result.
• A known-allowed jentic execute … (pointed at the right broker) returns a 2xx response body.