npm package: @knowstack/sdk
Description: CLI toolkit for KnowStack project setup and management
Latest version: 0.1.3

# @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](https://github.com/wellitongervickas/knowstack) instance

## Usage

```bash
npx @knowstack/sdk --init
```

With a named profile:

```bash
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:

```json
{
  "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).

```bash
# 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/`:

```bash
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`:

```json
"version": "X.Y.Z"
```

### 3. Verify the build

```bash
pnpm sdk:build
```

Fix any type errors before continuing.

### 4. Publish

From the repository root:

```bash
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

```bash
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`](../../docs/commands/sdk-release.md).

## License

MIT