Build an SDK

An SDK is a typed package containing only the services and operations one product needs. Authentication, retries, pagination, and provider quirks stay in the Engine. Your application code gets methods.

Author the config

fused-cli sdk init support-sdk \
  --service 'linear=v1' \
  --operation 'linear=issueUpdate' \
  --service 'slack=v1' \
  --operation 'slack=chatPostMessage'

That writes .fused/sdks/support-sdk.yaml:

apiVersion: fused/v1
kind: sdk
name: support-sdk
version: "1.0.0"
language: typescript
bucket: default
services:
  linear:
    version: "v1"
    operations: ["issueUpdate"]
  slack:
    version: "v1"
    operations: ["chatPostMessage"]

Each service key is an activated service’s Registry slug. Confirm one with fused-cli workspace services list -q <slug> — being visible in the Registry is not the same as being enabled here. operations and select_all: true are alternatives. Exactly one is required per service, never both and never neither.

init fills in the routing for you

Some provider hosts are templated — https://api-{app_id}.sendbird.com needs an app_id before it can be called. init spots those and writes the injection itself:

injections:
  - location: server_variable
    name: app_id
    value: ${bucket.env.SENDBIRD_APP_ID}
    mode: force

It reports how many it added. Re-running it never overwrites an injection you wrote yourself.

That value is a reference. Create the matching bucket entry with fused-cli value set before you plan, or there is nothing for dispatch to resolve.

Plan, apply, download

Validate the config

fused-cli sdk validate

Preview

fused-cli sdk plan

Plans are read-only. The receipt binds apply to this exact file content and this exact Engine.

Generate

fused-cli sdk apply --download

The first successful apply prints the SDK execution token once. Capture it immediately — an idempotent re-apply will not show it again, and it is never written to the config, the receipt, or CLI state.

Skip the package

Some SDKs are never imported. The product calls them over REST instead, and a generated package is dead weight. Set generate: false and apply publishes the version without building one:

generate: false

Nothing else changes. Same version, same operations, same execution contract — still callable at POST /v1/apps/{app_id}/executions, still describable with fused-cli sdk openapi. Only the download is gone: sdk apply --json reports generation.status: "skipped", and --download is refused before anything is applied. Flipping the field edits the file, which moves the source hash, so switching between the two needs a version bump like any other scope change.

Point the client at the Engine

The generated client takes grpcUrl — grpc_url in Python. The name is the instruction: it wants the Engine’s gRPC address, not the HTTP one you give the CLI.

const sdk = new FusedSDK({
  grpcUrl: process.env.FUSED_ENGINE_GRPC_URL,
  token: process.env.FUSED_SDK_TOKEN,
});

It resolves the target in this order, first non-empty wins:

grpcUrl / grpc_url passed to the constructor
FUSED_ENGINE_GRPC_URL
FUSED_ENGINE_URL
http://127.0.0.1:50051

Step 3 is the one that catches people. FUSED_ENGINE_URL is the HTTP management URL the CLI uses. If it is set in your environment and you do not pass grpcUrl, the client speaks gRPC at the REST port and the server answers HTTP 405. Set FUSED_ENGINE_GRPC_URL explicitly and the ambiguity goes away.

Each FusedSDK instance opens one gRPC channel that every service on it shares, so there is no per-service connection cost.

What is in the package

Alongside the typed client, generation writes two files from your actual selections:

File	For
`README.md`	Installing, authenticating, and calling the operations this SDK actually has
`SKILL.md`	A coding agent working in your repo

Both are derived from the generated source and validated against it, so the methods they demonstrate exist. Neither is a substitute for this site — they describe your package, not the platform.

Flags

`sdk init`

Flag	What it does	Example
`--service`	Adds a service at a version; repeatable	`fused-cli sdk init support --service 'linear=v1'`
`--operation`	Selects one operation; repeatable	`fused-cli sdk init support --operation 'linear=issueUpdate'`
`--select-all`	Takes every operation of a service	`fused-cli sdk init support --select-all 'linear'`
`--extend`	Adds to an existing config instead of refusing to overwrite	`fused-cli sdk init support --extend --service 'slack=v1'`
`--bucket`	References an existing bucket; never creates one	`fused-cli sdk init support --bucket prod-credentials`
`--version`	Sets the config version; defaults to `1.0.0`	`fused-cli sdk init support --version 2.0.0`
`--language`	`typescript` (default) or `python`	`fused-cli sdk init support --language python`

Creating never replaces an existing file. --extend is additive and idempotent — re-running it reports unchanged rather than duplicating a service.

`sdk plan`

Flag	What it does	Example
`--json`	Prints the plan result and required permissions	`fused-cli sdk plan --json`
`--interactive`	Securely fills credentials the Engine reports missing, then retries once	`fused-cli sdk plan --interactive`
`--owner-team`	Sets the owning team; defaults to you	`fused-cli sdk plan --owner-team payments`
`--receipt-out`	Writes the receipt to a chosen path	`fused-cli sdk plan --receipt-out ./ci/sdk.plan.json`

--interactive is incompatible with --json, --no-input, and CI=true. It never creates or substitutes a bucket.

`sdk apply`

Flag	What it does	Example
`--download`	Downloads the package after generating it	`fused-cli sdk apply --download`
`--json`	Returns apply, generation, and download outcomes	`fused-cli sdk apply --json`
`--plan-id`	Applies one exact remote plan	`fused-cli sdk apply --plan-id pln_a91…`
`--receipt`	Applies from a specific receipt	`fused-cli sdk apply --receipt ./ci/sdk.plan.json`

For pipelines, prefer separate apply and download steps so a failed transfer can be retried without replaying the apply.

Adjust the selection

fused-cli sdk service   <add|remove> <service-slug>
fused-cli sdk operation <add|remove> <service-slug> <operation-id...>

The service slug comes first, then as many operation IDs as you want:

fused-cli sdk service add zendesk --version v2
fused-cli sdk operation add linear issueCreate issueArchive
fused-cli sdk operation remove slack chatDelete

sdk operation add accepts --interactive to pick from a list, and --apply (or --download, which implies it) to push the change straight through.

Choosing auth

auth.type picks a Registry-declared scheme — basic, bearer, api_key, oauth, oidc, or mtls — and auth.name disambiguates two schemes of the same type.

services:
  linear:
    version: "v1"
    operations: ["issueUpdate"]
    auth: { type: "oauth" }
    connect: { scopes: ["read:issues", "write:issues"] }

Leave it out and the Engine picks each operation’s first provider-declared alternative. connect.scopes is a ceiling: an application can request fewer scopes per user, never more. The operation’s imported security requirements are authoritative, and they are an ordered OR of ANDs: alternatives are OR, schemes within one alternative are AND, and an empty alternative permits anonymous execution.

Do not collapse an AND alternative down to the one convenient scheme. A single selector never replaces a secondary credential such as an mTLS certificate or an additional API token — planning validates bucket metadata for every scheme in the chosen AND set.

Where a service declares several named schemes of one type, carry both the type and the exact name. Never rely on declaration order. Credentials themselves never appear in this file. They resolve from the bucket at generation and dispatch time.

Store the credentials

A plan that reports bucket_credentials_missing is telling you the bucket is not ready yet.

Get Started

Guides

Reference

Build an SDK

Author the config

init fills in the routing for you

Plan, apply, download

Skip the package

Point the client at the Engine

What is in the package

Flags

`sdk init`

`sdk plan`

`sdk apply`

Adjust the selection

Choosing auth

Store the credentials

​Author the config

​init fills in the routing for you

​Plan, apply, download

​Skip the package

​Point the client at the Engine

​What is in the package

​Flags

​sdk init

​sdk plan

​sdk apply

​Adjust the selection

​Choosing auth

Store the credentials

Author the config

init fills in the routing for you

Plan, apply, download

Skip the package

Point the client at the Engine

What is in the package

Flags

`sdk init`

`sdk plan`

`sdk apply`

Adjust the selection

Choosing auth