Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

sf connectors

Register tool sources for a team, connect accounts, set policy rules, and run connector tools from the terminal

Private Beta

sf connectors manages a team’s connectors: tool sources, the accounts connected to them, the policy rules that decide what agents may call, and runs. For the concepts and the dashboard, see Team connectors.

Connectors are in Private Beta. A team without access gets feature_unavailable and exits 2.

Every command takes the global flags (--api-url, --profile, --token, -y/--yes, --json) and -T/--team (team slug, ID, or name, env SPACEFAST_TEAM). Without --team, the server picks the team your credential acts for. A credential that can act for several teams must name one. See the CLI overview.

Every command needs a credential. Without one, it fails with auth_required and exit 10. sf connectors run checks its own input first.

API errors map to exit codes by HTTP status: 401 exits 10, 403 exits 11, 404 exits 20, 409 exits 30, and 422 exits 2. The tables below list the codes each command raises, both before the request and from the API.

sf connectors list

List the team’s connectors, with the connections your credential can use on each. Aliased as sf connectors ls.

sf connectors list [--query <value>] [--source openapi|graphql|mcp] [--limit <n>]

Flags

Flag Default What it does
--query=<value> none Filter over slug, title, and description
--source=<kind> none Show only openapi, graphql, or mcp connectors
--limit=<n> 50 Maximum connectors to return. Minimum 1, maximum 100
sf connectors list
sf connectors list --source mcp

Output

A table of SLUG | TITLE | SOURCE | TOOLS | CONNECTIONS. CONNECTIONS shows the count and the worst status among them, or none. An empty team prints No connectors. and Add one: sf connectors create <URL_OR_SLUG> on stderr.

With --json, the receipt is the API list envelope { data, pagination }.

sf connectors create

Register a connector. A URL is detected first, and the most confident candidate is registered. Any other value is looked up in the catalog.

sf connectors create <target> [--slug <value>] [--title <value>] [--description <value>]

Arguments

Argument What it is
<target> A spec, endpoint, or MCP URL, or a catalog slug. Required

Flags

Flag Default What it does
--slug=<value> detected or catalog slug Connector slug. Also the namespace of its tools
--title=<value> the source’s own name Display name
--description=<value> none Agent-visible note on what the connector reaches

A catalog lookup takes an exact id, registry id, or preset id match. Otherwise it takes the only search result.

sf connectors create https://api.example.com/openapi.json
sf connectors create linear --slug linear

Output

Registered <slug> (<title>) — <n> tools., then the command that connects an account. With --json, data is the connector.

Errors

Code Exit When
validation_error 2 <target> is missing
validation_error 2 Nothing recognizable behind the URL
validation_error 2 No catalog row matches, or several do. The message lists up to five ids
validation_error 2 The team already has that catalog row. The message names its slug
connector_slug_taken 30 The team already has a connector with that slug
connector_source_unreachable 2 The source did not load
connector_source_blocked 2 The URL is not reachable from Spacefast
rate_limited 1 More than 60 registrations, detections, or source refreshes in one hour for the team

sf connectors detect

Probe a URL and list the connectors behind it, most confident first. Nothing is registered.

sf connectors detect <url>

Arguments

Argument What it is
<url> Any http or https URL a service published. Required
sf connectors detect https://api.example.com

Output

A table of KIND | CONFIDENCE | SLUG | TITLE | ENDPOINT. CONFIDENCE is high, medium, or low. ENDPOINT is the URL to register, which can differ from the one you pasted. With --json, data is the array of candidates. Each carries kind, confidence, endpoint, title, slug, and presetId.

Errors

Code Exit When
validation_error 2 <url> is missing, or is not an http or https URL
rate_limited 1 Shares the hourly budget of sf connectors create

sf connectors delete

Delete a connector and its tools. Aliased as sf connectors rm and sf connectors del. Prompts unless you pass --yes.

sf connectors delete <connector>

Arguments

Argument What it is
<connector> Connector slug. Required

Deleting a connector disconnects every account on it first.

sf connectors delete linear --yes

Output

Deleted connector <slug> on stderr. When stdout is not a terminal, the slug also prints alone on stdout. With --json, data is { connector, removed: true }.

Errors

Code Exit When
confirmation_required 2 Non-interactive run without --yes
connector_first_party_immutable 30 The connector is built into Spacefast

sf connectors connections list

List the connections your credential can use: the team’s shared ones and your personal ones. Aliased as sf connectors connections ls.

sf connectors connections list [--owner team|personal|any] [--connector <slug>]
  [--status <status>] [--include-revoked] [--limit <n>]

Flags

Flag Default What it does
--owner=<value> any team, personal, or any
--connector=<slug> none Show only connections of this connector
--status=<value> none pending_authorization, active, degraded, needs_reauth, or revoked
--include-revoked false Include disconnected connections
--limit=<n> 50 Maximum connections to return. Minimum 1, maximum 100
sf connectors connections list
sf connectors connections list --owner personal

Output

A table of ID | CONNECTOR | OWNER | NAME | STATUS | TOOLS. (default) marks the connection an agent gets when it names the connector alone. With --json, the receipt is { data, pagination }.

sf connectors connections connect

Connect an account.

sf connectors connections connect <connector> [--api-key <value> | --field <name=value>...]
  [--owner team|personal] [--name <value>] [--description <value>] [--auth-method <slug>]

Arguments

Argument What it is
<connector> Connector slug. Required

Flags

Flag Default What it does
--api-key=<value> none API key for a connector that takes one. Never echoed back
--field=<name=value> none One credential value. Repeat it for each field. Splits on the first =
--owner=<value> team team shares it with the team. personal keeps it yours, within this team
--name=<value> the connector’s title Connection label
--description=<value> none Agent-visible note on what the connection is for
--auth-method=<slug> chosen by the server Auth method to use when the connector offers more than one
sf connectors connections connect stripe --api-key "$STRIPE_KEY"
sf connectors connections connect linear --owner personal

Output

The answer has one of three statuses.

Status Human output
connected Connected <name> as <id> — <n> tools.
authorization_required Open: <authorizeUrl> and its expiry. The provider callback finishes the connection
input_required One --field <name>=<value> line per value, with the provider’s help when it has some, and the auth method to pass back with --auth-method

With --json, data carries status and the matching fields: connection, authorizeUrl and expiresAt, or connector, authMethod, and fields.

Errors

Code Exit When
validation_error 2 <connector> is missing
validation_error 2 --api-key and --field are both set
validation_error 2 A --field value has no name= part
connection_forbidden 2 An API key asked for --owner personal
connection_needs_reauth 2 The credential was not stored, or the method does not fit the credential

sf connectors connections update

Change a connection’s label, its agent note, or its site-serving grant.

sf connectors connections update <connection> [--name <value>] [--description <value>]
  [--serving | --no-serving]

Arguments

Argument What it is
<connection> Connection id, for example cxn_abc123. Required

Flags

Flag Default What it does
--name=<value> unchanged New label. Must not be blank
--description=<value> unchanged New agent note. An empty string clears it
--serving, --no-serving unchanged Let Spaces bound to this team connection act as this account. See Connectors

Credentials cannot be edited. To rotate one, run sf connectors connections reconnect.

sf connectors connections update cxn_abc123 --name "Stripe (prod)"
sf connectors connections update cxn_abc123 --description "Billing, production"

Output

Updated <name> and ID <id> on stderr. With --json, data is the connection.

Errors

Code Exit When
validation_error 2 No flag to change, or --name is blank
connection_serving_not_granted 2 --serving on a personal connection

sf connectors connections health

Probe a connection against the provider. It only reports. An expired token refreshes on its own.

sf connectors connections health <connection>

Arguments

Argument What it is
<connection> Connection id. Required
sf connectors connections health cxn_abc123

Output

<id> <status> · <latency> · <n> tools, then the provider’s detail when something went wrong. A needs_reauth status adds the reconnect command. With --json, data carries connectionId, status, reachable, latencyMs, detail, toolCount, and checkedAt.

Errors

Code Exit When
connection_revoked 30 The connection is disconnected
connection_needs_reauth 30 The connection has no credential, or its authorization is not finished

sf connectors connections reconnect

Sign in again, or replace the credential, on the same connection. It keeps its id, label, policies, and Space bindings.

sf connectors connections reconnect <connection> [--api-key <value> | --field <name=value>...]

Arguments

Argument What it is
<connection> Connection id. Required

Flags

Flag Default What it does
--api-key=<value> none Replacement API key
--field=<name=value> none One replacement value. Repeat it for each field

Omit both flags for an OAuth connection. The answer is then an authorization URL.

sf connectors connections reconnect cxn_abc123
sf connectors connections reconnect cxn_abc123 --api-key "$STRIPE_KEY"

Output

The same three statuses as sf connectors connections connect. connected prints Reconnected <name> (<id>) — <n> tools.

Errors

Code Exit When
validation_error 2 --api-key and --field are both set, or a --field has no name= part
connection_revoked 30 The connection is disconnected. Connect the service again instead
invalid_request 2 The connector does not take the credential you passed

sf connectors connections refresh

Read the tool list behind a connection again, so tools the provider added or dropped show up.

sf connectors connections refresh <connection>

Arguments

Argument What it is
<connection> Connection id. Required
sf connectors connections refresh cxn_abc123

Output

Re-synced <name> (<id>) — <n> tools, <status>. With --json, data is the connection.

sf connectors connections disconnect

Disconnect a connection. The stored credential is purged and cannot be restored. Prompts unless you pass --yes.

sf connectors connections disconnect <connection>

Arguments

Argument What it is
<connection> Connection id. Required

Disconnecting an already disconnected connection changes nothing.

sf connectors connections disconnect cxn_abc123 --yes

Output

Disconnected <name>, ID <id>, and The credential is purged. on stderr. With --json, data is the connection with status revoked.

Errors

Code Exit When
confirmation_required 2 Non-interactive run without --yes

sf connectors policies list

List the policy rules in force: the team’s rules and your personal ones. Aliased as sf connectors policies ls.

sf connectors policies list

No command-specific flags.

sf connectors policies list

Output

A table of ID | PATTERN | ACTION | OWNER. With no rules, it prints “No rules. Every call falls through to the connector’s own default.” With --json, data is the array of rules. Each carries id, pattern, action, owner, position, and createdAt.

sf connectors policies add

Add a policy rule. Its position comes from the pattern’s specificity, so the more specific rule wins.

sf connectors policies add <pattern> --action <action> [--owner team|personal]

Arguments

Argument What it is
<pattern> *, <connector>/*, <connector>/<tool>, <connectionId>/*, or <connectionId>/<tool>. Quote it, because the shell expands a bare *. Required

Flags

Flag Default What it does
--action=<value> none, required approve runs the call. require_approval parks it for a person. block refuses it
--owner=<value> team team applies to everyone. personal applies to your own calls in this team

A team rule is a floor. A personal rule can tighten it, never loosen it.

sf connectors policies add '*' --action require_approval
sf connectors policies add 'cxn_abc123/charges.create' --action block

Output

Added <owner> rule <id> and Rule <pattern> → <action> on stderr. With --json, data is the rule.

Errors

Code Exit When
validation_error 2 <pattern> or --action is missing
malformed_policy_pattern 2 The pattern does not fit the grammar
connector_not_found 2 The pattern names a connector or connection the team does not have
connection_forbidden 2 An API key asked for --owner personal

sf connectors policies set

Change what a rule does. A rule’s pattern and owner are fixed. To change those, remove the rule and add a new one.

sf connectors policies set <rule> --action <action>

Arguments

Argument What it is
<rule> Rule id from sf connectors policies list. Required

Flags

Flag Default What it does
--action=<value> none, required approve, require_approval, or block
sf connectors policies set pol_abc123 --action block

Output

<id> is now <action> for <pattern>. With --json, data is the rule.

Errors

Code Exit When
validation_error 2 <rule> or --action is missing

sf connectors policies remove

Remove a rule. Its tools fall through to the next matching rule, or to the tool’s own default, so removing a block can open a tool again. Aliased as sf connectors policies rm. Prompts unless you pass --yes.

sf connectors policies remove <rule>

Arguments

Argument What it is
<rule> Rule id. Required
sf connectors policies remove pol_abc123 --yes

Output

Removed rule <id> on stderr. With --json, data is { policyRule, removed: true }.

Errors

Code Exit When
confirmation_required 2 Non-interactive run without --yes

sf connectors policies explain

Show what happens if you call one address, and why, without calling it.

sf connectors policies explain <address>

Arguments

Argument What it is
<address> Tool address, <connectionId>/<tool>. Required
sf connectors policies explain cxn_abc123/charges.create

Output

<address> → <effect>, then the deciding rule or “No rule matched.”, then the reason in one sentence. With --json, data carries address, effect, decidedBy (ruleId, pattern, owner, or null), and explanation.

Errors

Code Exit When
malformed_tool_address 2 The address does not resolve to a connection you can use

sf connectors run

Run one tool, or a program that calls several. Both are one run with one id.

sf connectors run [code] [--tool <address>] [--args <json>] [--wait <seconds>]
  [--idempotency-key <value>] [--deny-unattended]

Arguments

Argument What it is
[code] A program to run in the sandbox. It can call any tool your credential may use. Omit it with --tool

Flags

Flag Default What it does
--tool=<address> none Tool address, <connectionId>/<tool>, or <connector>/<tool> when one connection matches
--args=<json> {} JSON object of tool arguments. Accepts @file or - for stdin. Only with --tool
--wait=<seconds> the server’s, 30 seconds Seconds to wait for a final status. Minimum 0, maximum 120
--idempotency-key=<value> none Retry with the same key to get the original run back instead of running it twice
--deny-unattended false Fail at once instead of parking when a call needs approval

The run needs a credential with connectors:execute. A program runs for at most 10 seconds.

sf connectors run --tool cxn_abc123/issues.list --args '{"limit":5}'
sf connectors run --tool cxn_abc123/issues.create --args @issue.json

Output

Status Human output Exit
succeeded <id> succeeded · <n> tool call(s) · <ms>ms, then the result as JSON 0
failed <id> failed, then <code>: <detail> 1
awaiting_approval The address, Approve or deny: <approvalUrl>, and the expiry 0
expired parked too long; submit it again. 1
running still running., then sf connectors run inspect <id> 0

With --json, data is the run. Every run carries id, status, origin, input (kind, address, digest), usage (toolCalls, egressBytes, durationMs), and createdAt. A finished run adds completedAt, then result or error. A parked run adds approval with mode, address, preview, reason, matchedPattern, approvalUrl, and expiresAt.

A parked run expires after 15 minutes.

Errors

Code Exit When
validation_error 2 Both [code] and --tool, or neither
validation_error 2 --tool has no /
validation_error 2 --args with a program, or --args is not a JSON object
validation_error 2 --wait outside 0 to 120
idempotency_key_reused 30 The key was used with a different request
rate_limited 1 More than 1,200 runs in one hour for the team

A run that fails carries its reason in error.code, for example connector_tool_blocked, connection_ambiguous, connection_needs_reauth, or connector_approval_required.

sf connectors run inspect

Read one run: its result, its failure, or the approval it waits on. Use it to follow a running run.

sf connectors run inspect <run>

Arguments

Argument What it is
<run> Run id, for example cxr_abc123. Required
sf connectors run inspect cxr_abc123

Output

The same as sf connectors run, with the same exit codes.

sf connectors run list

List the team’s runs, newest first. Aliased as sf connectors run ls.

sf connectors run list [--status <status>] [--connection <id>] [--limit <n>]

Flags

Flag Default What it does
--status=<value> none running, awaiting_approval, succeeded, failed, or expired
--connection=<id> none Show only runs that touched this connection
--limit=<n> 50 Maximum runs to return. Minimum 1, maximum 100
sf connectors run list
sf connectors run list --status awaiting_approval

Output

A table of ID | STATUS | KIND | ADDRESS | CALLS | CREATED, or “No runs.” With --json, the receipt is { data, pagination }.

sf connectors run resume

Decide a parked run, or read back the decision a person made.

sf connectors run resume <run> [--accept | --deny | --cancel] [--content <json>]

Arguments

Argument What it is
<run> Run id. Required

Flags

Flag Default What it does
--accept false Approve the parked call
--deny false Refuse the parked call. The run fails with connector_tool_blocked
--cancel false Abandon the run
--content=<json> none JSON object of values the parked call asked for. Accepts @file or - for stdin

Omit the action to read back a decision a person recorded in the dashboard. A run parked for a person refuses a decision from the CLI.

sf connectors run resume cxr_abc123

Output

The same as sf connectors run, with the same exit codes.

Errors

Code Exit When
validation_error 2 More than one of --accept, --deny, and --cancel
validation_error 2 --content is not a JSON object
human_approval_required 11 An action was passed, and a person must decide this run in the dashboard
connector_approval_required 2 No action, and nobody has decided yet
connector_run_not_resumable 30 The run already settled, or someone else claimed the decision

Space bindings

These three commands connect a Space’s connector roles to team connections. They require --space or SPACEFAST_SPACE. For roles and bindings, see Connectors.

Command What it does
sf connectors bindings --space <ref> List the Space’s roles: `ROLE
sf connectors bind <role> <connection> --space <ref> Bind one role to a connection id
sf connectors unbind <role> --space <ref> Remove one binding. Prompts unless you pass --yes

Without --space or SPACEFAST_SPACE, each fails with validation_error and exit 2.

sf connectors also has serving and public-serving set commands. Run sf connectors serving --help for their flags.

Last updated on

Was this page helpful?