@growrk/cli 4.9.0

package/README.md

@@ -0,0 +1,173 @@
+# @growrk/cli
+
+`growrk` — the command-line interface for the **GroWrk v4 API**. It's a thin HTTP
+client over the same tool core that powers the REST API and the MCP server, so
+the CLI, `curl`, and an AI agent all reach the identical operations.
+
+```
+growrk CLI ──HTTP──> https://ai.growrk.com/v4/{resource} ──> GroWrk
+```
+
+## Installation
+
+```bash
+npm install -g @growrk/cli
+growrk --version
+```
+
+> Requires Node.js >= 24.
+
+## Authentication
+
+Every request is authenticated with a per-user API key (prefix `grk_sk_`) sent as
+the `X-API-KEY` header. One key works across the REST API, the CLI, and MCP.
+
+```bash
+# Interactive login (prompts for the API key and an account name)
+growrk auth login
+
+# Non-interactive
+growrk auth login --api-key grk_sk_... --environment prod --name production
+
+# Show the resolved identity + access for the active key
+growrk auth status
+
+# Remove a stored account
+growrk auth logout --name production
+```
+
+Credentials resolve in this order: `--api-key` flag → `GROWRK_API_KEY` env var →
+the active account in `~/.growrk/config.yml` (multiple named accounts supported).
+
+### Getting an API key
+
+1. In the GroWrk app, open **Developers → API Keys**.
+2. **Create API Key** → pick a company + app.
+3. Select the **Capabilities** the key should carry (e.g. `mcp:orders:read`,
+   `mcp:orders:write`, `mcp:employees:read`). These govern what the key can do on
+   the REST API and CLI; the key acts as you across every company you administer.
+4. Copy the raw key (shown once) and pass it to `growrk auth login`.
+
+## Commands
+
+Commands are grouped by resource: `growrk <resource> <action> [id] [flags]`. Run
+`growrk <resource> <action> --help` to see the exact flags for any action (they're
+generated from the shared tool schema, so they always match the API).
+
+### orders
+
+```bash
+growrk orders list --status shipped --limit 10       # GET  /v4/orders
+growrk orders get <orderId>                           # GET  /v4/orders/:id
+growrk orders create \                                # POST /v4/orders
+  --order-type "New Hire" --employee-id emp_123 --product-ids macbook-pro-14,dock
+growrk orders history <orderId>                       # GET  /v4/orders/:id/history
+growrk orders tracking <orderId>                      # GET  /v4/orders/:id/tracking
+growrk orders sla <orderId>                           # GET  /v4/orders/:id/sla
+growrk orders validate --order-type Deployment \      # POST /v4/orders/validate
+  --employee-id emp_123 --product-ids p1
+growrk orders add-accessory <orderId> ...             # POST /v4/orders/:id/accessories
+```
+
+### employees
+
+```bash
+growrk employees list                                 # GET   /v4/employees
+growrk employees get <employeeId>                     # GET   /v4/employees/:id
+growrk employees create ...                           # POST  /v4/employees
+growrk employees update <employeeId> --job-title Eng  # PATCH /v4/employees/:id
+growrk employees devices <employeeId>                 # GET   /v4/employees/:id/devices
+```
+
+### inventory & devices
+
+```bash
+growrk inventory search ...                           # GET /v4/inventory
+growrk devices options                                # GET /v4/devices/options
+growrk devices suggestions --country us               # GET /v4/devices/suggestions
+```
+
+### me
+
+```bash
+growrk me                                             # GET /v4/me — your identity + access
+```
+
+## Global options
+
+| Flag                  | Description                                                        |
+|-----------------------|-------------------------------------------------------------------|
+| `--api-key <key>`     | Override the stored API key                                       |
+| `--api-url <url>`     | Override the API base URL                                         |
+| `--environment <env>` | Target environment (`prod`, `io`, `local`)                        |
+| `--format <fmt>`      | Output format: `json`, `table`, `text` (default: `table`)        |
+| `--allow-localhost`   | Allow `http://localhost` for local development                    |
+| `--help`              | Show help                                                         |
+| `--version`           | Show the CLI version                                             |
+
+### Environments
+
+| Name    | URL                       | Notes                        |
+|---------|---------------------------|------------------------------|
+| `prod`  | `https://ai.growrk.com`   | Default                      |
+| `io`    | `https://io.growrk.com`   | Alias of prod (pre-cutover)  |
+| `local` | `http://localhost:3001`   | Requires `--allow-localhost` |
+
+```bash
+growrk orders list --environment prod
+```
+
+Any other target is reached with `--api-url`:
+
+```bash
+growrk orders list --api-url https://your-host.example.com
+```
+
+A stored account can also carry its own `apiUrl`
+(`growrk auth login --api-url <url> --name sandbox`), which becomes the active
+account only if it is your first one.
+
+The base URL resolves in this order:
+
+```
+--api-url  →  --environment  →  GROWRK_ENVIRONMENT  →  the account's environment
+           →  GROWRK_API_URL  →  the account's apiUrl  →  https://ai.growrk.com
+```
+
+`GROWRK_API_URL` sits near the end, so it is ignored if the active account
+already has an `environment` — use `--api-url` when you need to be certain.
+
+## Output formats
+
+| Format  | Description                                          |
+|---------|------------------------------------------------------|
+| `table` | Aligned columns for the terminal (default)           |
+| `json`  | Full JSON envelope with `ok`, `data`, `meta`         |
+| `text`  | Plain text, suitable for piping                      |
+
+```bash
+growrk orders list --format json | jq '.data.orders[0].id'
+```
+
+## The same API, three ways
+
+The CLI is one of three surfaces over the same tool core:
+
+```bash
+# REST
+curl https://ai.growrk.com/v4/orders -H "X-API-KEY: grk_sk_..."
+
+# CLI
+growrk orders list
+
+# MCP (Streamable HTTP) — OAuth 2.1, or X-API-KEY
+POST https://ai.growrk.com/mcp
+```
+
+## Development
+
+```bash
+pnpm build   # bundle with tsup
+pnpm dev     # watch mode
+pnpm test    # vitest
+```

package/bin/growrk.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// Thin, committed launcher for the `growrk` bin.
+//
+// pnpm links bins during install BEFORE workspace `prepare` scripts run, and
+// `pnpm cleanup` wipes `dist/` — so pointing `bin` directly at the tsup output
+// (`dist/cli.mjs`) makes pnpm warn "Failed to create bin … ENOENT" on a fresh
+// install until `prepare` rebuilds it. This launcher always exists in the repo
+// (and in the published `files`), so the bin link never fails; it just defers
+// to the real CLI built by tsup.
+import('../dist/cli.mjs').catch((err) => {
+  console.error('[growrk] CLI build not found — run `pnpm -F @growrk/cli build`.')
+  console.error(err?.message ?? err)
+  process.exit(1)
+})

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }