engram-connect 0.1.1

Thin Engram command-line client

CLI

Owns the first engram command-line client for connecting a developer machine to an already-running Engram server.

Current command surface:

python -m engram_cli connect --server URL --api-key KEY --project PROJECT
python -m engram_cli doctor
python -m engram_cli hook post-tool-use < hook.json
python -m engram_cli hook session-start < context.json
python -m engram_cli hook error < hook.json
python -m engram_cli hook decision < hook.json
python -m engram_cli hook session-start --response-format codex < hook.json
python -m engram_cli disconnect

The package declares two console scripts in pyproject.toml that share the same entrypoint: engram (short, for typed commands) and engram-connect (matches the distribution name, so uvx engram-connect ... works without --from).

Plug-and-play install (engram install)

engram install is the one-command onboarding path for a Claude Code harness. It validates the server, API key, and project scope (same dry-run as connect), writes local credentials under ~/.engram, installs the Engram Claude Code plugin through the native claude plugin marketplace, and finishes with a doctor health check.

Run it without cloning the repo via uvx:

uvx engram-connect install \
  --server <URL> --api-key <KEY> --project <PROJECT_ID>

Before the package is published to PyPI, install straight from git or pipx:

uvx --from "git+https://github.com/Barsoomx/engram.git#subdirectory=packages/cli" \
  engram install --server <URL> --api-key <KEY> --project <PROJECT_ID>
# or:
pipx install engram-connect
engram install --server <URL> --api-key <KEY> --project <PROJECT_ID>

The plugin steps run claude plugin marketplace add <--marketplace-source> then claude plugin install <--plugin-name>@<--marketplace-name> using the claude binary on PATH (override with --claude-bin). Pass --skip-plugin-install to write credentials and run doctor without touching the harness. The bundled plugin hooks require python3 >= 3.12 on PATH.

Local state defaults to $ENGRAM_HOME when set, otherwise ~/.engram. connect writes only Engram-owned config, credential, and hook-manifest files. doctor is read-only. disconnect removes only Engram-owned files. Hook commands read one JSON object from stdin, merge the connected project, team, runtime, and credential metadata, and call the Engram server. By default they print the server JSON response. Codex response mode prints the Codex hook response instead.

The CLI must not introduce a persistent local memory service, local database, provider secrets, embeddings, cached memory bundles, durable event queue, or background summarization behavior.

Run tests from the repository root:

PYTHONPATH=packages/cli python3 -m unittest discover -s packages/cli -p '*_tests.py' -v