sf connectors
Register tool sources for a team, connect accounts, set policy rules, and run connector tools from the terminal
Private Betasf 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.