npm package: @prajwolkc/stk
Description: One CLI to deploy, monitor, debug, and learn about your entire stack. Infrastructure monitoring, knowledge base brain, deploy watching, and GitHub issues — all from one command.
Author: prajwolkc
Latest version: 0.9.0

# stk

One CLI to deploy, monitor, and debug your entire stack.

Stop opening 5 dashboards. `stk` checks your services, watches your deploys, syncs your env vars, tails your logs, and manages your issues — all from one command.

<!-- TODO: Add demo GIF here -->
<!-- ![stk demo](./docs/demo.gif) -->

## Install

```bash
npm install -g @prajwolkc/stk
```

## Quick Start

```bash
cd my-project
stk init                      # auto-detect your services
stk init --template saas      # or use a starter template
stk doctor                    # diagnose any misconfig
stk health                    # check everything
stk status                    # one-line summary of your whole stack
```

## Commands

| Command | Description |
|---------|-------------|
| `stk init` | Initialize config (auto-detect or `--template saas\|api\|fullstack\|static\|fly\|aws`) |
| `stk status` | One-line summary: git, services, deploys, issues |
| `stk health` | Health check all configured services |
| `stk doctor` | Diagnose misconfig, missing env vars, and suggest fixes |
| `stk deploy` | Git push + watch deploy providers |
| `stk env pull` | Pull env vars from Vercel + Railway into `.env.pulled` |
| `stk env diff` | Show what's in your local `.env` |
| `stk logs` | Tail logs from Railway, Vercel, Fly, or Render |
| `stk logs -p vercel` | Logs from a specific provider |
| `stk todo ls` | List open GitHub issues |
| `stk todo add "title"` | Create a GitHub issue |
| `stk todo close 42` | Close an issue |

## Supported Services

**Deploy providers:** Railway, Vercel, Fly.io, Render, AWS
**Databases:** PostgreSQL, MongoDB, Redis, Supabase
**Storage & billing:** Cloudflare R2, Stripe
**Custom:** Add your own via plugins

## Configuration

`stk init` creates a `stk.config.json` in your project root:

```json
{
  "name": "my-saas",
  "services": {
    "vercel": true,
    "railway": true,
    "database": true,
    "redis": true,
    "stripe": true,
    "r2": true
  },
  "deploy": {
    "branch": "main",
    "providers": ["vercel", "railway"]
  }
}
```

Only configured services are checked — no noise from services you don't use.

If no config file exists, `stk` auto-detects services from your environment variables.

## Templates

```bash
stk init --list-templates
```

| Template | Stack |
|----------|-------|
| `saas` | Vercel + Railway + PostgreSQL + Redis + Stripe + R2 |
| `api` | Railway + PostgreSQL + Redis |
| `fullstack` | Vercel + Railway + Supabase + Stripe |
| `static` | Vercel only |
| `fly` | Fly.io + PostgreSQL + Redis |
| `aws` | AWS + PostgreSQL + Redis |

## Doctor

`stk doctor` scans your config and environment to catch issues before they bite:

```
$ stk doctor

  my-saas — Doctor
  ─────────────────────────────────────────
  ✓  railway      Configured correctly
  ✗  vercel       Missing required: VERCEL_TOKEN
                   See https://vercel.com/account/tokens
  !  database     Missing optional: RAILWAY_PROJECT_ID
                   Some features need these for full functionality
  ✓  stripe       Configured correctly
```

## Plugins

Add custom services without forking. Create `.stk/plugins/my-service.mjs`:

```js
export default {
  name: "my-plugin",
  services: {
    myservice: {
      name: "My Service",
      envVars: ["MY_SERVICE_TOKEN"],
      healthCheck: async () => {
        const token = process.env.MY_SERVICE_TOKEN;
        if (!token) {
          return { name: "My Service", status: "skipped", detail: "MY_SERVICE_TOKEN not set" };
        }
        // Your check logic here
        return { name: "My Service", status: "healthy", detail: "connected" };
      }
    }
  }
};
```

Plugins are automatically loaded by `stk health` and `stk health --all`.

## Environment Variables

```bash
# Deploy providers
RAILWAY_API_TOKEN=
VERCEL_TOKEN=
FLY_API_TOKEN=
FLY_APP_NAME=              # needed for stk logs -p fly
RENDER_API_KEY=
AWS_ACCESS_KEY_ID= / AWS_SECRET_ACCESS_KEY=

# Databases
DATABASE_URL=
MONGODB_URL=
REDIS_URL=
SUPABASE_URL= / SUPABASE_SERVICE_KEY=

# Storage & billing
CLOUDFLARE_ACCOUNT_ID= / CLOUDFLARE_API_TOKEN=
STRIPE_SECRET_KEY=

# GitHub (for stk todo)
GITHUB_TOKEN=
GITHUB_REPO=owner/repo   # or auto-detected from git remote
```

## Claude Code / MCP Integration

`stk` ships with a built-in MCP server so Claude Code can use your infrastructure as native tools.

### Setup

1. Install stk globally:

```bash
npm install -g @prajwolkc/stk
```

2. Add to your project's `.mcp.json` (create it in your project root):

```json
{
  "mcpServers": {
    "stk": {
      "command": "stk-mcp",
      "args": []
    }
  }
}
```

3. Restart Claude Code. Approve the stk MCP server when prompted.

### What Claude can do

| Tool | Description |
|------|-------------|
| `stk_health` | Check if all services are up before writing code |
| `stk_status` | Full overview: git, services, deploys, issues |
| `stk_doctor` | Diagnose misconfig and missing env vars |
| `stk_logs` | Read production logs to understand bugs |
| `stk_todo_list` | See what needs to be worked on |
| `stk_todo_add` | Create GitHub issues |
| `stk_deploy` | Push code and trigger deploys |
| `stk_config` | Read the project's stack config |

### Example prompts

- *"Check if all my services are healthy"*
- *"What errors are in my production logs?"*
- *"What should I work on next?"*
- *"Deploy this and verify it worked"*

## Development

```bash
git clone https://github.com/Harden43/stk.git
cd stk
npm install
npm run dev -- health --all     # run in dev mode
npm test                        # run tests
npm run build                   # compile TypeScript
```

## License

MIT