User CLI

pgm is the standard Postgram client for human and agent workflows. It wraps entity storage, search, graph operations, task management, markdown document sync, queue status, and backups.

What this page covers

Every user-facing pgm command, what it does, and all positional arguments and options exposed by the CLI.

Setup

The CLI reads the Postgram endpoint and API key from the environment:

export PGM_API_URL=http://127.0.0.1:3100
export PGM_API_KEY=your-api-key

Install from npm:

npm install -g @ivotoby/postgram-cli

In development, run the TypeScript entrypoint from the Postgram repo:

npx tsx cli/src/pgm.ts <command>

Usage

pgm [--json] <command> [arguments] [options]

Global options:

• --json: emit compact machine-friendly JSON where the command supports it.
• --help: show help.
• --version: show the CLI version.

Output options

• --json returns compact JSON for agent and script use.
• --json --full-response returns the full REST-shaped response on commands that expose --full-response.
• --toon returns compact human-readable text for list-like output on commands that expose --toon.
• --toon cannot be combined with --json or --full-response.

Entity commands

pgm store [content]

Alias: pgm add [content]

Stores an entity. Use this for durable facts, notes, and records. If content is omitted, the CLI reads content from standard input.

Arguments:

• [content]: entity content.

Options:

• --type <type>: entity type. Defaults to memory.
• --visibility <visibility>: entity visibility. Defaults to shared.
• --owner <owner>: entity owner or namespace.
• --status <status>: entity status.
• --tags <tags>: comma-separated tags.
• --source <source>: source label or URI.
• --metadata <json>: JSON metadata object.
• --skip-extraction: store without queueing graph extraction.
• --full-response: with --json, emit the full API response.

Example:

pgm store "Use pgvector for semantic search" \
  --type memory \
  --visibility personal \
  --tags decisions,search

pgm search <query>

Searches stored entities with semantic search. It can optionally include graph-connected entities.

Arguments:

• <query>: search query.

Options:

• --type <type>: filter by entity type.
• --tags <tags>: filter by comma-separated tags.
• --visibility <visibility>: filter by visibility.
• --owner <owner>: filter by owner.
• --limit <limit>: result limit. Defaults to 10.
• --threshold <threshold>: similarity threshold. Defaults to 0.35.
• --recency-weight <recencyWeight>: recency weight. Defaults to 0.1.
• --expand-graph: include graph-connected entities in results.
• --include-archived: include archived entities in results.
• --memory-role <role>: filter memory entities by session_context or durable_memory.
• --full-response: with --json, emit the full API response.
• --toon: emit compact TOON output.

Example:

pgm search "deployment constraint" \
  --type memory \
  --memory-role durable_memory \
  --limit 5 \
  --toon

Compact search output may include an edge summary:

"edges": {
  "count": 3,
  "relations": [{ "relation": "mentioned_in", "count": 2 }]
}

Use --expand-graph or pgm expand <entity-id> when those relation hints are relevant to the question. For direct facts already present in the result, keep the search compact.

pgm recall <id>

Fetches one entity by ID.

Arguments:

• <id>: entity ID.

Options:

• --owner <owner>: owner filter.

pgm list

Lists entities with optional filters.

Arguments:

• None.

Options:

• --type <type>: filter by type.
• --status <status>: filter by status.
• --visibility <visibility>: filter by visibility.
• --owner <owner>: filter by owner.
• --tags <tags>: filter by comma-separated tags.
• --limit <limit>: result limit. Defaults to 50.
• --offset <offset>: result offset. Defaults to 0.
• --include-archived: include archived entities.
• --full-response: with --json, emit the full API response.
• --toon: emit compact TOON output.

pgm update <id>

Updates an entity. The command uses optimistic versioning: pass --version from a prior recall, list, or JSON response, or use --force to fetch the latest version before updating.

Arguments:

• <id>: entity ID.

Options:

• --content <content>: updated content.
• --visibility <visibility>: updated visibility.
• --status <status>: updated status.
• --tags <tags>: comma-separated replacement tag list.
• --source <source>: updated source.
• --metadata <json>: replacement JSON metadata object.
• --version <version>: expected entity version.
• --force: retry using the latest version on conflict.
• --full-response: with --json, emit the full API response.

Example:

pgm update <entity-id> --content "Revised note" --version 3

pgm delete <id>

Soft-deletes an entity.

Arguments:

• <id>: entity ID.

Options:

• None.

Agent memory commands

pgm memory session-context [content]

Alias: pgm memory session [content]

Stores short-lived client-scoped session context for agent resumability. Prefer this command over pgm store for active work state, blockers, hypotheses, and next steps. If content is omitted, the CLI reads content from standard input.

Arguments:

• [content]: session-context content.

Options:

• --visibility <visibility>: entity visibility. Defaults to shared.
• --owner <owner>: entity owner or namespace.
• --session-id <sessionId>: external session or thread ID.
• --agent-id <agentId>: agent or persona metadata only. It is not an auth boundary.
• --topic <topic>: topic label.
• --tags <tags>: comma-separated tags.
• --promotable: mark this session context as promotable after distillation.
• --groom-after <groomAfter>: ISO timestamp after which grooming may archive or promote it.
• --expires-at <expiresAt>: ISO timestamp after which the context is stale.
• --full-response: with --json, emit the full API response.

Example:

pgm memory session-context \
  "Session context: working on docs. Next step: run build." \
  --topic postgram-website \
  --tags postgram-website,session-context \
  --visibility personal

pgm memory groom

Previews or archives stale session_context memories for the authenticated client.

Arguments:

• None.

Options:

• --dry-run: preview without mutating.
• --older-than <duration>: include memories older than a duration such as 15m, 2h, or 7d. Defaults to 7d.
• --limit <limit>: maximum candidates.
• --topic <topic>: filter by topic.
• --session-id <sessionId>: filter by session ID.
• --tag <tag>: filter by tag. Repeat for multiple tags.
• --yes: confirm archive mutation. Required unless --dry-run is set.

Examples:

pgm memory groom --dry-run --topic postgram-website --tag session-context
pgm memory groom --older-than 30d --topic postgram-website --tag session-context --yes

Task commands

pgm task add [content]

Creates a task entity. If content is omitted, the CLI reads content from standard input.

Arguments:

• [content]: task content.

Options:

• --context <context>: GTD context such as @desk or @calls.
• --status <status>: task status. Defaults to inbox.
• --due <dueDate>: due date.
• --tags <tags>: comma-separated tags.
• --visibility <visibility>: task visibility. Defaults to shared.
• --metadata <json>: JSON metadata object.
• --full-response: with --json, emit the full API response.

Example:

pgm task add "Review graph extraction notes" --context @desk --status next

pgm task list

Lists task entities.

Arguments:

• None.

Options:

• --status <status>: filter by status.
• --context <context>: filter by context.
• --limit <limit>: result limit. Defaults to 50.
• --offset <offset>: result offset. Defaults to 0.
• --include-archived: include archived tasks.
• --full-response: with --json, emit the full API response.
• --toon: emit compact TOON output.

pgm task update <id>

Updates a task. --version is required.

Arguments:

• <id>: task ID.

Options:

• --content <content>: updated content.
• --context <context>: updated GTD context.
• --status <status>: updated status.
• --due <dueDate>: updated due date.
• --tags <tags>: comma-separated replacement tag list.
• --visibility <visibility>: updated task visibility.
• --metadata <json>: replacement JSON metadata object.
• --version <version>: expected task version. Required.
• --full-response: with --json, emit the full API response.

pgm task complete <id>

Marks a task complete. --version is required.

Arguments:

• <id>: task ID.

Options:

• --version <version>: expected task version. Required.
• --full-response: with --json, emit the full API response.

Document sync commands

pgm sync <dir>

Syncs a local directory of markdown files. The CLI walks .md files recursively, computes SHA-256 hashes locally, uploads only changed files, and archives server-side documents that are no longer present in the local manifest.

Arguments:

• <dir>: directory path to sync.

Options:

• --repo <name>: repository identifier. Defaults to the directory name.
• --dry-run: show what would change without syncing.
• --quiet: suppress human-readable output.

Example:

pgm sync ~/Documents/notes --repo notes --dry-run
pgm sync ~/Documents/notes --repo notes --quiet

Graph commands

pgm link <source-id> <target-id>

Creates an edge between two entities.

Arguments:

• <source-id>: source entity ID.
• <target-id>: target entity ID.

Options:

• --relation <relation>: relationship type. Required.
• --confidence <n>: confidence score from 0 to 1. Defaults to 1.0.
• --full-response: with --json, emit the full API response.

Example:

pgm link <source-id> <target-id> --relation depends_on --confidence 0.9

pgm unlink <edge-id>

Deletes an edge.

Arguments:

• <edge-id>: edge ID.

Options:

• None.

pgm expand <entity-id>

Shows the graph neighborhood of an entity.

Arguments:

• <entity-id>: entity ID.

Options:

• --depth <n>: traversal depth from 1 to 3. Defaults to 1.
• --relation <types>: comma-separated relation types.
• --owner <owner>: owner filter.
• --full-response: with --json, emit the full API response.
• --toon: emit compact TOON output.

Example:

pgm expand <entity-id> --depth 2 --relation depends_on,mentions --toon

Operations commands

pgm queue

Shows embedding and extraction queue status.

Arguments:

• None.

Options:

• None.

pgm backup

Creates a database backup. The command uses local pg_dump when available and falls back to docker compose exec for the configured Postgres service.

Arguments:

• None.

Options:

• --output <path>: backup output file or directory. Required.
• --encrypt: encrypt the backup with GPG.

Environment used by backup:

• DATABASE_URL or PGM_DATABASE_URL: database connection string. Required.
• PGM_BACKUP_DOCKER_SERVICE: Docker Compose service name. Defaults to postgres.
• PGM_BACKUP_DOCKER_USER: database user for Docker fallback. Defaults to postgram.
• PGM_BACKUP_DOCKER_DB: database name for Docker fallback. Defaults to postgram.
• PGM_BACKUP_PASSPHRASE: GPG passphrase. Required with --encrypt.

Example:

pgm backup --output ~/backups/
pgm backup --output ~/backups/postgram.dump.gpg --encrypt

Quick command map

Use this map when you know the goal but not the command name:

• Store durable facts: pgm store
• Store resumable active work state: pgm memory session-context
• Find information: pgm search, pgm recall, pgm list
• Update or remove entities: pgm update, pgm delete
• Manage tasks: pgm task add, pgm task list, pgm task update, pgm task complete
• Sync markdown folders: pgm sync
• Manage graph edges: pgm link, pgm unlink, pgm expand
• Check enrichment workers: pgm queue
• Back up the database: pgm backup

Notes

• Commands that accept [content] read from standard input when the argument is omitted.
• --tags <tags> accepts a comma-separated list such as docs,website.
• --metadata <json> must be a JSON object string.
• Update commands use optimistic versioning. Capture the returned version from JSON output before updating in scripts.