Skip to content

Latest commit

 

History

History
104 lines (91 loc) · 8.17 KB

api-and-cli.md

File metadata and controls

104 lines (91 loc) · 8.17 KB

API and CLI

Concepts

  • Scope: global or project/<name>.
  • Project: name = basename of git repo root of cwd (main repo in a worktree). No .pcm file in project.
  • Section: user defined (e.g. style, review). One folder per section.
  • Context: one md file. A section can have many contexts (e.g. backend.md, ui.md). Many contexts can apply to one project.
  • Binaries: pcm-server (API server, runs in background) and pcm (CLI client, calls API).
  • Home: ~/.pcm/ holds config.yaml, server.pid, server.log, index/ (Bleve search index) and repo/. Only repo/ is synced.
  • Repo: separate git repo. Default ~/.pcm/repo, user can select other path with pcm config set path <dir>.
  • First run: no init command. If repo folder is missing, pcm creates it and runs git init -b main. If remote is not set, pcm sync and pcm sync status print:
    info: remote not set, contexts are local only
    hint: pcm config set remote <git-url> && pcm sync
    
  • Layout: <repo>/<scope>/<section>/<name>.md
  • Search: Bleve index in ~/.pcm/index/, cache only. md files are source of truth. Server updates it on context create and update. Rebuilt after any delete (context, section, project), after sync, on pcm index rebuild, and on server start if missing or schema changed (in background).
  • Sync: manual only. CLI pcm sync or UI sync button. Server runs the git CLI (uses user's SSH agent, ~/.ssh/config, credential helpers). Branch main.
    1. git add -A, commit pcm sync: N files changed if changes.
    2. No remote: stop. Else set origin (add or set-url), fetch, rebase on origin/main.
    3. Conflict: git rebase --abort, 409 with files. Fix by hand in repo, then pcm sync.
    4. Push if ahead (-u origin main). Server reads remote from config.yaml on each call: no restart needed. Timeouts: CLI health 2s, API calls 30s, sync 5m. Server finishes a sync even if the client disconnects. pcm sync status before the first push: ahead = local commits, hint run pcm sync to push.
  • Claude Code: skill calls CLI. No MCP.

REST API (/api/v1)

GET /health (root, not under /api/v1): health check.

Method Path Purpose
GET /projects List projects
POST /projects Create project
GET /projects/{project} Get project
DELETE /projects/{project} Delete project
GET /sections List sections
POST /sections Create section
DELETE /sections/{section} Delete section
GET /contexts?scope=&project=&section= List contexts with filters
GET /contexts/{id} Read context (md + metadata)
POST /contexts Create context
PUT /contexts/{id} Update context
DELETE /contexts/{id} Delete context
GET /search?q=&scope=&project=&global=&section=&limit= Full-text search (Bleve) in title, name, description, tags, content, section and project. Fuzzy, ranked, all scopes by default. project=X only X; project=X&global=true global + X. limit default 20, must be > 0. Query: words OR, +word must, -word must not, "phrase" exact. Hit: id, scope, project, section, name, title (name if none), description, snippet (HTML escaped, <mark>), score
POST /index/rebuild Rebuild search index from md files
GET /resolve?project=&section= Merged global + project contexts with content. Project overrides global on same section/name. No project: global only
GET /git/status branch, remote, changes (porcelain), ahead, behind (from last fetch)
POST /git/sync Commit, pull --rebase, push. 409 {"error","files"} on conflict
GET /git/log?n=10 Recent commits: hash, date, message
GET /config Read config
PUT /config Update config (remote URL, author)
GET /* Embedded React app

CLI (pcm)

k8s style: pcm <verb> <resource> [name] [flags]. Output is a table. No short names.

Command Purpose
pcm get context(s) [-s <section>] [-p <project>] Current contexts: project: line, then table SCOPE, NAME, SECTION, TITLE, DESCRIPTION, UPDATED. Global first, then project (-p or git repo). Project overrides global on same section/name. Not in git repo: global only
pcm get context(s) -g [-s <section>] Global contexts only (no SCOPE column)
pcm get context <name> -s <section> [-p <project> | -g] Print md file (frontmatter + content)
pcm create context <name> -s <section> (-m <text> | -f <file|->) [--title] [--description] [--tag ...] [--force] [-p <project> | -g] Create context. --force replaces existing (PUT)
pcm delete context <name> -s <section> [-p <project> | -g] Delete context
pcm edit context <name> -s <section> Open in $EDITOR (later)
pcm search <query> [-s <section>] [-p <project> | -g | --all] [--limit 20] Search contexts. No flag: global + git repo project; not in git repo: all. -p: global + project. -g: global only. --all: all. Table: SCOPE, NAME, SECTION, TITLE, SNIPPET, SCORE. Matches bold on a terminal
pcm index rebuild Rebuild search index from md files
pcm get contexts -o md [-s <section>] [-p <project> | -g] Merged global + project contexts as markdown (for skill). Not in git repo: global only
pcm get project(s) [name] List projects or show one
pcm create project <name> Create project
pcm delete project <name> [--force] Delete project (--force if not empty)
pcm get section(s) [-p <project> | -g] List sections in a scope
pcm create section <name> [-p <project> | -g] Create section
pcm delete section <name> [-p <project> | -g] [--force] Delete section (--force if not empty)
pcm sync Commit, pull, push. Output: committed, pulled, pushed
pcm sync status Branch, remote, changes, ahead, behind, changed files
pcm sync log [-n 10] Recent commits (HASH, DATE, MESSAGE)
pcm health Check server is reachable (text output, exit 1 if not)
pcm --version, pcm-server --version Print <name> <version> (commit <sha>, built <date>). No server needed. Release builds set the values with ldflags (internal/version); local builds print dev
pcm server start Start pcm-server in background (pid/log in ~/.pcm/)
pcm server stop Stop background server
pcm server status Show server health and pid
pcm config get [key] Print all keys or one. Keys: path, remote, port, swagger
pcm config set <key> <value> Write key to config.yaml. path / port / swagger: hint to restart server. swagger: true or false (default), serves API docs UI at /swagger/

Scope flags (like kubectl -n): -p <project> or -g (global). Both: error. No flag: current project = main repo folder name: parent of git rev-parse --path-format=absolute --git-common-dir when it ends in .git (same for worktrees), else git rev-parse --show-toplevel. Normalized (My.Repo → my-repo). Needs git 2.31+.

  • Not in git repo: error, hint use -p <project> or -g.
  • create auto-creates the current project. get / delete do not.
  • -p <project> never auto-creates (typo safety).

Claude Code skill

Source: internal/skill/SKILL.md, embedded in pcm with go:embed.

Command Purpose
pcm skill install Write SKILL.md to ~/.claude/skills/pcm/ (overwrite)
pcm skill uninstall Remove ~/.claude/skills/pcm/
pcm skill show Print SKILL.md

Skill: start server if needed, load pcm get contexts -o md at start of coding task and before review, save with pcm create context when user asks to remember, dump session rules and decisions to a project context named after the PR title (fallback: branch, then a name the user approves) on request (user approves first; content written to a scratchpad file and saved with -f <file>; asks overwrite with --force or new name with -2 suffix), manage contexts on request. Before gh pr create: load contexts (and review section), check commit messages and branch name against the rules (reports only, never rewrites history), show title and body and wait for approval. allowed-tools: Bash(pcm:*), Bash(gh pr view:*), Bash(gh pr create:*), Bash(git branch:*), Bash(git log:*), Write.