@knowstack/sdk

CLI toolkit for KnowStack project setup and management.

Connects to a running KnowStack API via MCP, creates your organization and project, ingests documents, and seeds agents, skills, commands, and templates — all in one interactive flow.

Requirements

• Node.js >= 18
• A running KnowStack API instance

Usage

npx @knowstack/sdk --init

With a named profile:

npx @knowstack/sdk --init --profile staging

Options

| Flag | Description | |------|-------------| | --init | Start the interactive setup wizard | | --profile <name> | Use or create a named profile | | --version, -v | Print the installed version | | --help, -h | Show usage information |

What --init Does

The wizard walks through these steps:

1. Load or create a profile from knowstack.config.json
2. Prompt for the MCP endpoint URL (default: http://localhost:3100/api/v1/mcp)
3. Health-check the API
4. Create or select an organization
5. Create or select a project
6. Select context projects (for cross-project knowledge)
7. Save the profile locally
8. Ingest documents from ./docs/
9. Seed agents, skills, commands, and templates from ./docs/agents/, ./docs/skills/, etc.
10. Generate embeddings (async, non-blocking)
11. Print setup summary

Configuration

The wizard saves your choices to knowstack.config.json in the directory where you run the command. Each named profile stores:

{
  "profiles": {
    "default": {
      "mcpUrl": "http://localhost:3100/api/v1/mcp",
      "organizationId": "...",
      "projectId": "...",
      "documentsDir": "./docs",
      "contextProjects": []
    }
  }
}

Development

All commands run from the repository root (packages/sdk/ is a pnpm workspace package).

# Build the SDK
pnpm sdk:build

# Watch mode
pnpm --filter @knowstack/sdk dev

# Type-check only
pnpm --filter @knowstack/sdk typecheck

Or from inside packages/sdk/:

pnpm build       # compile TypeScript → dist/
pnpm dev         # watch mode
pnpm typecheck   # tsc --noEmit
pnpm clean       # rm -rf dist

Publishing a New Version

1. Decide the version bump

| Change | Bump | Example | |--------|------|---------| | Bug fix, metadata update | patch | 0.1.2 → 0.1.3 | | New feature or step | minor | 0.1.2 → 0.2.0 | | Breaking change (CLI args, config format) | major | 0.1.2 → 1.0.0 |

2. Update the version

Edit packages/sdk/package.json:

"version": "X.Y.Z"

3. Verify the build

pnpm sdk:build

Fix any type errors before continuing.

4. Publish

From the repository root:

pnpm sdk:release

This runs: clean → build → npm publish --access public.

You need to be authenticated (npm login) and a member of the @knowstack npm organization. If 2FA is enabled, you will be prompted for an OTP.

5. Verify

npm view @knowstack/sdk version   # should match the version you set
npx @knowstack/sdk --version      # should print the new version
npx @knowstack/sdk --help         # should respond correctly

For the full checklist including troubleshooting, see docs/commands/sdk-release.md.

License

MIT