Run a Sim Integration Tool

Sim holds the credentials. Read what the tool declares, bind auth from that declaration, and run it. Never put a live credential in the command.

Preflight

• tools execute requires a personal API-key profile; a workspace API key is refused.
• Find the tool with sim --output json tools list --search <term>, then read it with sim --output json tools get <toolId>. Never guess a tool id or a parameter name.
• An unversioned name resolves to the newest version visible in the workspace, and the response echoes the id that answered. Use that id in the call.
• Use a Function block for code requiring workflow execution context. An executor-delegation error from function_execute is not a missing user credential; do not invent internal context fields or change authentication to bypass it.

Bind auth from the declaration, not from habit

tools get labels every parameter with a visibility, and the label says where its value comes from:

• user-or-llm — you supply it in --input.
• user-only — you supply it, but pass a reference instead of the secret: {{VAR_NAME}} as the whole value, resolved server-side. List the available names with sim --output json secrets list; values are never returned. Any other value is sent verbatim. One exception: a parameter named credential or oauthCredential is the credential selector, not a secret — see below. It is refused in --input.
• hidden — Sim fills it. Never put it in --input; it is refused.

Then bind the credential by the tool's own shape:

• The tool declares oauth.required, or declares a required credential or oauthCredential parameter (Snowflake and others do the latter, with no oauth block) — find the credential with sim --output json credentials list --provider-id <provider> and pass --credential-id. It is the one place a credential is named; Sim places it where the tool expects it. Omitting it fails naming credentialId; putting it in --input under any spelling is refused.
• hostedApiKey is always, or conditional and this call matches — omit the key entirely; Sim supplies its own and bills the workspace.
• Otherwise the tool takes its own user-only key parameter; pass a {{VAR_NAME}} reference.

Your Sim login governs platform access; the selected provider credential determines the external identity. A different OAuth connection can act as a different bot or user. Do not substitute one to bypass an ownership error or a mismatch between advertised and accepted authentication modes.

--input accepts exactly what tools get publishes as yours to send. An undeclared key, a hidden one, or a credential under any name is a 400 that names the offending field — read it rather than guessing at a spelling.

Run and read the outcome

sim --output json tools execute <toolId> --credential-id <id> --input '{"...": "..."}'

--input also accepts @path or @-, which is how a payload too large or too awkward to quote reaches the command.

A tool result with status: "failed" exits non-zero and reports its reason in error.message. Read that reason to distinguish execution setup failure from a provider refusal; the status alone does not prove the service received the request. A 403 carrying error.details.code INTEGRATION_NOT_ALLOWED is a workspace policy decision, not a fixable argument — say so and stop.

Tool results follow the provider's pagination contract. When more pages remain, use the published cursor before reporting a total; the CLI's resource-list pagination does not paginate tool results.

Invariants

• Never print a resolved secret, an OAuth token, or a profile credential. You hold a credential id and a variable name; that is all the call needs.
• Do not retry a failed write blind. A tool call is not idempotent, and a retry can duplicate the message, issue, or record the first attempt created.
• Build a workflow instead when the task needs more than one call, branching, or a schedule.