Documentation

CLI & SDK

The @duct-sdk/sdk package ships the duct CLI and typed manifest helpers. These commands are how you authenticate, scaffold duct.config.ts, publish manifests, and diagnose your integration — the fastest path from “how do I wire this?” to a working shell.

@duct-sdk/sdk

Official npm package — CLI, typed manifest helpers, and framework adapters for Node.js 20+.

npm packageSDK imports
$ npm i @duct-sdk/sdk

Typical first run

Link your workspace, generate a manifest, push it live, then verify connectivity.

$ npx @duct-sdk/sdk login
$ npx @duct-sdk/sdk init --manual
$ npx @duct-sdk/sdk push
$ npx @duct-sdk/sdk checkup

Full CLI reference →

Run from your product repo

All commands use npx @duct-sdk/sdk <command> so you do not need a global install. Node.js 20+ is required for the CLI only — your API can be any language.

Command Reference

login

Authenticate the CLI with your Duct API key. Credentials are stored in ~/.duct/auth.json (mode 600).

bash
npx @duct-sdk/sdk login
npx @duct-sdk/sdk login --token dk_live_...
npx @duct-sdk/sdk login --logout

Get your key from the dashboard after signup. Set DUCT_API_KEY in CI instead of interactive login.

init

Generate or refresh duct.config.ts in the current directory. Full init prints a wiring plan before writing files, generates middleware snippets under .duct/snippets/, validates the manifest before write, and runs an integration audit afterward.

bash
npx @duct-sdk/sdk init --manual          # blank, typed template — recommended first path
--manual
Topology + file selection only. No LLM. Best for learning the manifest shape or hand-authoring actions.
--update
Re-scan the repo and merge new detections into duct.config.ts.
--api-spec
Build actions from an OpenAPI/Swagger file; RouteAgent still discovers UI routes and deeplinks in parallel. Handles partial specs — missing operationId values get derived IDs; component schemas via $ref are resolved when possible.
--curl-collection
Build actions from a .sh curl script or Postman Collection v2.1 JSON — same deterministic path as --api-spec.
--dry-run
Print generated files without writing them.

push

Validate duct.config.ts and publish the manifest to your shell in Duct cloud. Increments manifest_version.

bash
npx @duct-sdk/sdk push
npx @duct-sdk/sdk push --dry-run       # validate only, no upload

After push, the hosted shell picks up the new manifest promptly under normal conditions — cache invalidation runs on push, and versioned cache keys mitigate concurrent stale refills. See manifest versions & side-effect changes for what that means for consent.

checkup

Verify environment variables and reachability of Duct services (auth, API, shell, and dashboard). When duct.config.ts is present, also runs the same integration audit as post-init (token route, receiver, embed mount, env template, deeplink targets, middleware wiring).

bash
npx @duct-sdk/sdk checkup

scan

Compare duct.config.ts against live API endpoints or the last pushed snapshot.

bash
npx @duct-sdk/sdk scan                    # probe live endpoints vs manifest
npx @duct-sdk/sdk scan --manifest-diff  # diff local config vs .duct-manifest.json (CI-safe)
npx @duct-sdk/sdk scan --json

pull & rollback

Restore a previous manifest from push history.

bash
npx @duct-sdk/sdk pull a3f9b12            # write historical manifest to duct.config.ts
npx @duct-sdk/sdk rollback a3f9b12       # activate a historical push as the live manifest (no local file change)
npx @duct-sdk/sdk rollback a3f9b12 --yes

pull is for local recovery. rollback activates a historical push as the live manifest (no local file change) — enforcement updates promptly under normal conditions, with the same consent rules as a normal push.

promote

Copy the live manifest from one shell to another (e.g. dev → staging → prod).

bash
npx @duct-sdk/sdk promote --from shell_acme_dev --to shell_acme_prod

npm Package Imports

The CLI is one entry point. Your app also imports helpers from subpaths — see the SDK import guide and frameworks page for embed and token wiring.

bash
npm install @duct-sdk/sdk

Next Steps

Quickstart

End-to-end path from login to embedded shell.

Configuration

Manifest fields, permissions, and version behavior.