@pokelo/cli 0.1.0

package/README.md

@@ -0,0 +1,121 @@
+# pokelo
+
+Official CLI for [Pokelo](https://pokelo.bearly.pro) — a thin client over the **public REST API** (`/v1`), designed for AI agents, skills, CI, and shell automation.
+
+CLI does **not** call MCP. MCP remains a separate adapter for IDEs that support it.
+
+| npm package | Binary |
+|-------------|--------|
+| `@pokelo/cli` | `pokelo` |
+
+## Install
+
+```bash
+npm install -g @pokelo/cli
+pokelo --help
+```
+
+From this monorepo (before publish / local dev):
+
+```bash
+pnpm --filter @pokelo/cli exec pokelo --help
+# or
+node tools/pokelo-cli/bin/pokelo.mjs --help
+
+cd tools/pokelo-cli && pnpm link --global
+pokelo --help
+```
+
+Requires Node.js ≥ 18 (uses global `fetch`).
+
+Agent skill (Cursor): [`.cursor/skills/pokelo-cli/`](../../.cursor/skills/pokelo-cli/) — also shipped under `skill/` in the npm package.
+
+## Auth (agents)
+
+Non-interactive (required for headless agents):
+
+```bash
+pokelo auth login \
+  --url https://pokelo.example.com \
+  --token "$POKELO_TOKEN"
+```
+
+Safer token input (not visible in `ps`):
+
+```bash
+printenv POKELO_TOKEN | pokelo auth login --url https://pokelo.example.com --token-stdin
+```
+
+Or skip the config file entirely:
+
+```bash
+export POKELO_URL=https://pokelo.example.com
+export POKELO_TOKEN=mcp_…
+export POKELO_PROJECT=my-project-slug   # optional default
+pokelo projects list
+```
+
+Interactive (TTY):
+
+```bash
+pokelo auth login
+```
+
+Check config (never prints the full token):
+
+```bash
+pokelo auth status
+```
+
+### Config priority
+
+```text
+CLI flags (--url, --token, --project)
+  > environment (POKELO_URL, POKELO_TOKEN, POKELO_PROJECT)
+  > ~/.config/pokelo/config.json
+  > legacy ~/.pokelo-cli.json (read-only migrate of url/token)
+```
+
+URL may be `https://host` or `https://host/v1` — normalized to `…/v1`.
+
+Create a Personal Access Token in the Pokelo UI (Settings → MCP / PAT). Prefix is `mcp_`; the same token works for REST and MCP.
+
+## Commands
+
+```bash
+pokelo projects list
+pokelo projects get <project-id-or-slug>
+
+pokelo search "how does auth work" --project <ref> --limit 5
+
+pokelo docs list --project <ref>
+pokelo docs get <document-id-or-slug> --project <ref>
+pokelo docs create --title "Note" --type Note --content "# Hi" --project <ref>
+pokelo docs update <id> --content-file ./body.md --project <ref>
+
+pokelo assets list --project <ref>
+pokelo assets get <asset-id> --project <ref>
+pokelo assets upload ./shot.png --project <ref> --description "screenshot"
+pokelo assets download <asset-id> --out ./shot.png --project <ref>
+pokelo assets update <asset-id> --name "renamed.png" --project <ref>
+pokelo assets delete <asset-id> --project <ref>
+```
+
+`assets upload` uses `POST …/assets/base64` for files ≤ 8 MiB; larger files use init → PUT → complete.
+
+Stdout is always JSON. Errors go to stderr.
+
+Exit codes: `0` ok, `1` usage/config, `2` API/network.
+
+## Agent happy path
+
+```bash
+pokelo auth login --url https://pokelo.example.com --token "$TOKEN"
+pokelo search "jak działa auth" --project khirby --limit 5
+pokelo docs get <document-id> --project khirby
+pokelo assets upload ./diagram.png --project khirby
+```
+
+## Spec
+
+Product SSOT: *Pokelo CLI — public API client for agents (Single Source of Truth)* in the Pokelo project.

package/bin/pokelo.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.mjs';
+
+main(process.argv.slice(2)).catch((err) => {
+  const msg = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`Error: ${msg}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@pokelo/cli",
+  "version": "0.1.0",
+  "description": "Official Pokelo CLI — public REST client for agents and developers",
+  "type": "module",
+  "bin": {
+    "pokelo": "./bin/pokelo.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "skill"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "pokelo",
+    "knowledge-base",
+    "cli",
+    "rag",
+    "agents"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node ./bin/pokelo.mjs",
+    "pokelo": "node ./bin/pokelo.mjs"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: pokelo-cli
+description: >-
+  Uses the Pokelo CLI (`pokelo` binary from npm package `@pokelo/cli`) over the
+  public REST API for auth, projects, semantic search, documents, and assets.
+  Use when working with Pokelo knowledge bases from the shell, provisioning
+  agents without MCP, or when the user mentions pokelo CLI, @pokelo/cli, or
+  PAT-based Pokelo access.
+disable-model-invocation: false
+---
+
+# Pokelo CLI
+
+Official shell client for Pokelo. Speaks **public REST `/v1` + Personal Access Token** — never MCP.
+
+| Concept | Value |
+|---------|--------|
+| npm package | `@pokelo/cli` |
+| Command on PATH | `pokelo` |
+| Config | flags > `POKELO_*` env > `~/.config/pokelo/config.json` |
+
+## 1. Ensure installed (idempotent)
+
+Run before the first `pokelo` call in a session:
+
+```bash
+# From package install or checkout:
+bash skill/scripts/ensure-pokelo.sh
+# Or: command -v pokelo || npm install -g @pokelo/cli
+```
+
+Or manually:
+
+1. If `command -v pokelo` succeeds → **do not install**; use it.
+2. Else: `npm install -g @pokelo/cli` (exposes the `pokelo` binary).
+3. In this monorepo only, if npm package is unpublished: use
+   `node tools/pokelo-cli/bin/pokelo.mjs` or symlink it to `~/.local/bin/pokelo`.
+
+Never reinstall when `pokelo` is already available.
+
+## 2. Auth
+
+Prefer env in CI / ephemeral sandboxes (no disk write):
+
+```bash
+export POKELO_URL=https://<host>          # or http://localhost:3001 for local API
+export POKELO_TOKEN=mcp_…                 # Personal Access Token
+export POKELO_PROJECT=<slug-or-uuid>      # optional default
+```
+
+Or persist config (agents, headless):
+
+```bash
+pokelo auth login --url "$POKELO_URL" --token-stdin <<< "$POKELO_TOKEN"
+# or: pokelo auth login --url … --token "$TOKEN"
+pokelo auth status   # never prints the full token
+```
+
+Local Vite (`:5173`) does **not** proxy `/v1` — point `POKELO_URL` at the API (`:3001`), not the frontend.
+
+## 3. Commands (stdout = JSON)
+
+```bash
+pokelo projects list
+pokelo projects get <project-ref>
+
+pokelo search "<query>" --project <ref> [--limit n]
+
+pokelo docs list --project <ref>
+pokelo docs get <doc-ref> --project <ref>
+pokelo docs create --title "…" [--type] [--content|--content-file] [--parent] --project <ref>
+pokelo docs update <doc-ref> [--title] [--content|--content-file] --project <ref>
+
+pokelo assets list --project <ref>
+pokelo assets get <asset-id> --project <ref>
+pokelo assets upload <file> [--name] [--mime] [--visibility] [--document] [--description] --project <ref>
+pokelo assets download <asset-id> --out <path> --project <ref>
+pokelo assets update <asset-id> [--name] [--description] … --project <ref>
+pokelo assets delete <asset-id> --project <ref>
+```
+
+Exit codes: `0` ok, `1` usage/config, `2` API/network. Errors on stderr.
+
+`assets upload`: ≤ 8 MiB → `POST …/base64`; larger → init → PUT → complete.
+
+## 4. Agent workflow
+
+1. Ensure `pokelo` is installed (step 1).
+2. Confirm auth (`auth status` or env vars).
+3. Resolve project (`projects list` / known slug).
+4. `search` → if snippets are thin, `docs get`.
+5. Write only when asked (`docs create/update`, `assets upload`).
+6. Do **not** echo tokens; do **not** call MCP from this skill.
+
+## 5. Extra detail
+
+- Command cheat sheet: [reference.md](reference.md)
+- This directory is the copy shipped inside the `@pokelo/cli` npm package (`skill/`).

package/skill/reference.md

@@ -0,0 +1,59 @@
+# Pokelo CLI reference
+
+## Package vs binary
+
+```text
+npm i -g @pokelo/cli   →  installs package @pokelo/cli
+                       →  binary name: pokelo
+```
+
+## Config priority
+
+```text
+--url / --token / --project
+  > POKELO_URL / POKELO_TOKEN / POKELO_PROJECT
+  > ~/.config/pokelo/config.json
+  > legacy ~/.pokelo-cli.json (read for migration on login)
+```
+
+URL forms `https://host` and `https://host/v1` both normalize to `…/v1`.
+
+## Auth
+
+| Command | Notes |
+|---------|--------|
+| `pokelo auth login --url U --token T` | Persist config; never echo T |
+| `pokelo auth login --url U --token-stdin` | Token from stdin |
+| `pokelo auth login` | Interactive TTY only |
+| `pokelo auth status` | Masked preview `mcp_…****` |
+
+## Projects / search / docs
+
+| Command | REST |
+|---------|------|
+| `projects list` | `GET /projects` |
+| `projects get <ref>` | `GET /projects/:id` |
+| `search "q" -p <ref> -l n` | `POST /projects/:id/documents/search` |
+| `docs list -p <ref>` | `GET /projects/:id/documents` |
+| `docs get <ref> -p <ref>` | `GET /projects/:id/documents/:id` |
+| `docs create --title …` | `POST /projects/:id/documents` |
+| `docs update <ref> …` | `PATCH /projects/:id/documents/:id` |
+
+## Assets
+
+| Command | REST |
+|---------|------|
+| `assets list` | `GET /projects/:id/assets` |
+| `assets get <id>` | `GET /projects/:id/assets/:id` |
+| `assets upload <file>` | `POST …/base64` or uploads+complete |
+| `assets download <id> --out F` | get + downloadUrl / content redirect |
+| `assets update <id>` | `PATCH /projects/:id/assets/:id` |
+| `assets delete <id>` | `DELETE /projects/:id/assets/:id` |
+
+Filters for list: `--type`, `--source`, `--visibility`, `--document`, `--page`, `--limit`.
+
+## Safety
+
+- Never print the full PAT.
+- Prefer `--token-stdin` or env over `--token` when possible.
+- Do not commit `~/.config/pokelo/config.json`.

package/skill/scripts/ensure-pokelo.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Ensure the `pokelo` binary is on PATH. No-op if already available.
+# npm package name: @pokelo/cli  →  CLI command: pokelo
+set -euo pipefail
+
+if command -v pokelo >/dev/null 2>&1; then
+  echo "pokelo already available: $(command -v pokelo)"
+  exit 0
+fi
+
+if command -v npm >/dev/null 2>&1; then
+  echo "Installing @pokelo/cli (provides \`pokelo\` binary)…"
+  if npm install -g @pokelo/cli; then
+    if command -v pokelo >/dev/null 2>&1; then
+      echo "Installed: $(command -v pokelo)"
+      exit 0
+    fi
+    echo "Package installed but \`pokelo\` not on PATH; check npm global bin." >&2
+  else
+    echo "npm install -g @pokelo/cli failed (package may be unpublished)." >&2
+  fi
+fi
+
+# Monorepo / package-local fallbacks
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CANDIDATES=(
+  # skill shipped inside tools/pokelo-cli/skill/scripts
+  "$SCRIPT_DIR/../../bin/pokelo.mjs"
+  # .cursor/skills/pokelo-cli/scripts → repo tools/pokelo-cli
+  "$SCRIPT_DIR/../../../tools/pokelo-cli/bin/pokelo.mjs"
+)
+
+mkdir -p "${HOME}/.local/bin"
+for candidate in "${CANDIDATES[@]}"; do
+  if [[ -f "$candidate" ]]; then
+    ln -sfn "$candidate" "${HOME}/.local/bin/pokelo"
+    export PATH="${HOME}/.local/bin:${PATH}"
+    if command -v pokelo >/dev/null 2>&1; then
+      echo "Linked local CLI: $candidate → ~/.local/bin/pokelo"
+      exit 0
+    fi
+  fi
+done
+
+echo "Error: could not locate or install pokelo." >&2
+echo "Fix: npm install -g @pokelo/cli   OR   symlink tools/pokelo-cli/bin/pokelo.mjs" >&2
+exit 1

package/src/cli.mjs

@@ -0,0 +1,256 @@
+import { fail } from './exit.mjs';
+import { runAssets } from './commands/assets.mjs';
+import { runAuth } from './commands/auth.mjs';
+import { runDocs } from './commands/docs.mjs';
+import { runProjects } from './commands/projects.mjs';
+import { runSearch } from './commands/search.mjs';
+
+function printHelp() {
+  process.stdout.write(
+    `pokelo — Pokelo public API CLI for agents and developers
+
+Usage:
+  pokelo auth login --url <url> --token <token>
+  pokelo auth login --url <url> --token-stdin
+  pokelo auth login
+  pokelo auth status
+
+  pokelo projects list
+  pokelo projects get <project-id-or-slug>
+
+  pokelo search "<query>" [--project <ref>] [--limit <n>]
+
+  pokelo docs list [--project <ref>]
+  pokelo docs get <document-id-or-slug> [--project <ref>]
+  pokelo docs create --title <t> [--type] [--content|--content-file] [--parent] [--project]
+  pokelo docs update <document-id-or-slug> [options]
+
+  pokelo assets list [--project] [--type] [--visibility] [--document]
+  pokelo assets get <asset-id> [--project]
+  pokelo assets upload <file> [--name] [--mime] [--visibility] [--document] [--description]
+  pokelo assets download <asset-id> --out <path> [--project]
+  pokelo assets update <asset-id> [--name] [--description] [--visibility] [--document]
+  pokelo assets delete <asset-id> [--project]
+
+Global options:
+  --project, -p <ref>   Project UUID or slug (or POKELO_PROJECT / config default)
+  --url <url>           Instance URL (overrides env/config)
+  --token <token>       Personal Access Token (overrides env/config; prefer env/--token-stdin)
+  --json                Accepted for compatibility (stdout is always JSON)
+  --help, -h            Show help
+
+Config (priority: flags > env > file):
+  POKELO_URL, POKELO_TOKEN, POKELO_PROJECT
+  ~/.config/pokelo/config.json
+
+Exit codes: 0 ok, 1 usage/config, 2 API/network error
+`,
+  );
+}
+
+/**
+ * Minimal argv parser: supports long flags, -p/-l/-h, and --flag=value.
+ * @param {string[]} argv
+ */
+export function parseArgs(argv) {
+  /** @type {Record<string, unknown>} */
+  const flags = {};
+  const positional = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--') {
+      positional.push(...argv.slice(i + 1));
+      break;
+    }
+    if (arg === '--help' || arg === '-h') {
+      flags.help = true;
+      continue;
+    }
+    if (arg === '--json') {
+      flags.json = true;
+      continue;
+    }
+    if (arg === '--token-stdin') {
+      flags.tokenStdin = true;
+      continue;
+    }
+    if (arg === '--tree') {
+      flags.tree = true;
+      continue;
+    }
+
+    const eq = arg.match(/^--([a-zA-Z0-9-]+)=(.*)$/);
+    if (eq) {
+      setFlag(flags, eq[1], eq[2]);
+      continue;
+    }
+
+    if (arg === '--project' || arg === '-p') {
+      flags.project = needValue(argv, ++i, arg);
+      continue;
+    }
+    if (arg === '--limit' || arg === '-l') {
+      flags.limit = parseInt(needValue(argv, ++i, arg), 10);
+      continue;
+    }
+    if (arg === '--page') {
+      flags.page = parseInt(needValue(argv, ++i, arg), 10);
+      continue;
+    }
+    if (arg === '--url') {
+      flags.url = needValue(argv, ++i, arg);
+      continue;
+    }
+    if (arg === '--token') {
+      flags.token = needValue(argv, ++i, arg);
+      continue;
+    }
+    if (arg === '--title') {
+      flags.title = needValue(argv, ++i, arg);
+      continue;
+    }
+    if (arg === '--type') {
+      flags.type = needValue(argv, ++i, arg);
+      continue;
+    }
+    if (arg === '--content') {
+      flags.content = needValue(argv, ++i, arg);
+      continue;
+    }
+    if (arg === '--content-file') {
+      flags.contentFile = needValue(argv, ++i, arg);
+      continue;
+    }
+    if (arg === '--parent') {
+      flags.parent = needValue(argv, ++i, arg);
+      continue;
+    }
+    if (arg === '--status') {
+      flags.status = needValue(argv, ++i, arg);
+      continue;
+    }
+    if (arg === '--search' || arg === '-q') {
+      flags.search = needValue(argv, ++i, arg);
+      continue;
+    }
+    if (arg === '--name') {
+      flags.name = needValue(argv, ++i, arg);
+      continue;
+    }
+    if (arg === '--mime' || arg === '--mime-type') {
+      flags.mime = needValue(argv, ++i, arg);
+      continue;
+    }
+    if (arg === '--visibility') {
+      flags.visibility = needValue(argv, ++i, arg);
+      continue;
+    }
+    if (arg === '--document' || arg === '--document-id') {
+      flags.document = needValue(argv, ++i, arg);
+      continue;
+    }
+    if (arg === '--description') {
+      flags.description = needValue(argv, ++i, arg);
+      continue;
+    }
+    if (arg === '--source') {
+      flags.source = needValue(argv, ++i, arg);
+      continue;
+    }
+    if (arg === '--out') {
+      flags.out = needValue(argv, ++i, arg);
+      continue;
+    }
+
+    if (arg.startsWith('-')) {
+      fail(`unknown option: ${arg}`);
+    }
+    positional.push(arg);
+  }
+
+  return { flags, positional };
+}
+
+function needValue(argv, index, flag) {
+  if (index >= argv.length) fail(`missing value for ${flag}`);
+  return argv[index];
+}
+
+function setFlag(flags, name, value) {
+  const map = {
+    project: 'project',
+    limit: 'limit',
+    page: 'page',
+    url: 'url',
+    token: 'token',
+    title: 'title',
+    type: 'type',
+    content: 'content',
+    'content-file': 'contentFile',
+    parent: 'parent',
+    status: 'status',
+    search: 'search',
+    name: 'name',
+    mime: 'mime',
+    'mime-type': 'mime',
+    visibility: 'visibility',
+    document: 'document',
+    'document-id': 'document',
+    description: 'description',
+    source: 'source',
+    out: 'out',
+  };
+  const key = map[name];
+  if (!key) fail(`unknown option: --${name}`);
+  if (key === 'limit' || key === 'page') {
+    flags[key] = parseInt(value, 10);
+  } else {
+    flags[key] = value;
+  }
+}
+
+/**
+ * @param {string[]} argv
+ */
+export async function main(argv) {
+  const { flags, positional } = parseArgs(argv);
+
+  if (flags.help || positional.length === 0) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const cmd = positional[0];
+  const rest = positional.slice(1);
+
+  switch (cmd) {
+    case 'help':
+      printHelp();
+      break;
+    case 'auth':
+      await runAuth(rest, flags);
+      break;
+    case 'projects':
+      await runProjects(rest, flags);
+      break;
+    case 'search':
+      await runSearch(rest, flags);
+      break;
+    case 'docs':
+      await runDocs(rest, flags);
+      break;
+    case 'assets':
+      await runAssets(rest, flags);
+      break;
+    // Back-compat aliases from MCP PoC
+    case 'list':
+      await runDocs(['list', ...rest], flags);
+      break;
+    case 'get':
+      await runDocs(['get', ...rest], flags);
+      break;
+    default:
+      fail(`unknown command: ${cmd}\nRun: pokelo --help`);
+  }
+}