synaply

Talk to your Synaply Memory from the terminal — and let any AI assistant (Claude Code, Codex, Cursor, ChatGPT, Gemini, anything that follows pasted rules) read and write to your private cloud second-brain.

npm install -g synaply
synaply login           # paste your token (Settings → CLI access in Synaply)
synaply init            # set up your AI tools to know about Synaply
synaply memory ls       # you're done

That's the whole setup. ~30 seconds.

What it does

The Synaply CLI is the bridge between your terminal (and the AIs running there) and your private cloud second-brain in Synaply. Every memory you read or write is per-user, per-tenant, encrypted at rest, audit-logged, and recoverable forever.

• 🧠 Read — search, list, fetch full memories with their bodies, why-rationale, and how-to-apply guidance
• ✍️ Write — capture decisions, war stories, projects, todos, feedback, references straight from the terminal
• 🤖 AI-native — synaply init writes neutral instructions into whichever rules format your AI tools use (CLAUDE.md, AGENTS.md, .cursorrules, etc.) so they all know how to use it
• 🔍 Searchable — hybrid full-text + vector search via the same engine that powers the web app's ⌘K palette
• 🔐 Privacy-first — only memories belonging to the signed-in user are visible. No admin override.

Install

npm install -g synaply

Requires Node ≥ 18.

Auth

The CLI uses a bearer token that's tied to your active Synaply session.

1. Open https://<your-tenant>.synaply.io/settings/cli in your browser.
2. Click Reveal → Copy token.
3. In your terminal:

   synaply login

   Paste the token. The CLI verifies it by hitting the API, then saves to ~/.synaply/config.json (mode 0600).
4. Confirm with synaply status.

Tokens expire when your web session expires. Just paste a fresh one — same drill.

Scripted / CI usage

Skip synaply login entirely with env vars:

export SYNAPLY_TOKEN="<paste your token>"
export SYNAPLY_BASE_URL="https://your-tenant.synaply.io"   # or .synaplystg.com for staging
synaply status

Env vars override ~/.synaply/config.json, so you can flip between tenants per-shell.

Hook into your AI tools

synaply init figures out which AI assistant rules files exist and writes neutral, AI-agnostic Synaply instructions into them. Run it from the project root.

synaply init

It detects:

| AI tool | Where it writes | |---|---| | Claude Code (project) | CLAUDE.md | | Claude Code (global) | ~/.claude/CLAUDE.md | | Codex / OpenAI Codex CLI | AGENTS.md | | Cursor (legacy) | .cursorrules | | Cursor (modern) | .cursor/rules/synaply.mdc | | Cline (VS Code) | .clinerules | | Aider | CONVENTIONS.md | | GitHub Copilot Chat | .github/copilot-instructions.md |

Always also writes a canonical copy at .synaply/INSTRUCTIONS.md you can @-reference.

Variants

synaply init                              # interactive — pick which detected tools to write to
synaply init --all                        # write to every detected tool
synaply init --tool claude-code           # write only to CLAUDE.md
synaply init --tool cursor-mdc            # write only to .cursor/rules/synaply.mdc
synaply init --print                      # print rules to stdout (for ChatGPT, Gemini, etc.)
synaply init --print | pbcopy             # macOS — copy rules to clipboard
synaply init --yes                        # skip confirmation prompts

Re-running synaply init updates the existing rules block (marked with <!-- synaply:start --> / <!-- synaply:end -->) without clobbering anything else in the file.

For AIs without rules files

Pasteable into ChatGPT custom instructions, Gemini system prompt, Mistral, etc.:

synaply init --print

Copy the output, paste into your AI's "system prompt" / "custom instructions" field. Done.

Commands

synaply memory ls                           # list memories
synaply memory ls --type PROJECT            # filter by type
synaply memory ls --tag project_network     # filter by tag
synaply memory ls -q "stripe"               # free-text search across name+description
synaply memory get <id>                     # show one in full (body, why, howToApply)
synaply memory new --type DECISION \
  --name "..." --description "..." \
  --body "..." --why "..."                  # capture a memory (body can pipe from stdin)
synaply memory edit <id>                    # opens $EDITOR on the body
synaply memory verify <id>                  # mark still accurate (resets staleness clock)
synaply memory archive <id> --reason "..."  # soft archive (recoverable forever via restore)
synaply memory restore <id>                 # bring back from archive
synaply memory forget <id>                  # queue hard delete (7-day window — restore cancels)
synaply memory search "query"               # hybrid FTS + vector search
synaply memory todo                         # active TODOs only
synaply memory export > backup.json         # full export
synaply status                              # show current auth state
synaply login                               # paste a fresh token
synaply logout                              # clear stored token
synaply init                                # set up AI rules files
synaply --help                              # full command reference

Pipe-friendly

Body can come from stdin — either by omitting --body entirely, or by passing --body - (the unix convention, useful when the rest of the flags are scripted and you want to be explicit):

git log -1 --format=%B | synaply memory new \
  --type WAR_STORY \
  --name "Why I rolled back the deploy" \
  --description "What went wrong with #783"

# Equivalent, with an explicit stdin sentinel:
cat changelog.md | synaply memory new --body - \
  --type DECISION \
  --name "..." \
  --description "..."

Export is JSON — pipe through jq:

synaply memory export | jq -r '.files[] | .content'

synaply memory edit <id> opens your $EDITOR on a temp file. Save + close to PATCH the memory. Same audit trail as the web UI.

Git context awareness

Inside a git repo, the CLI auto-captures branch / commitSha / worktree / hasChanges / prNumber on every write. Those fields show up on the memory's revision history in the web UI so you can later filter "memories from PR #785" or "memories I wrote on feature/X."

Outside a git repo, no git fields are sent. The web UI hides git terminology entirely for non-dev users.

Privacy + security

• Memories are per-user, per-tenant. Even if you belong to multiple tenants, your memories DO NOT cross.
• All memory bodies are encrypted at rest with KMS-style per-tenant keys.
• Every write produces an immutable revision row with source attribution (CLI + agent name + git context).
• The CLI's bearer token is your NextAuth session JWT — the same token your browser sends on every API call. Don't commit it.
• The synaply tool itself is MIT-licensed and open-source (this repo). The Synaply backend it talks to is closed-source.

Develop

Local iteration without npm link:

git clone <synaply repo>
cd packages/cli
npm install
npm run dev -- memory ls   # tsx runs the TS source directly

Build + global link for repeated local testing:

npm run build
npm link
synaply --version          # 0.2.0

License

MIT — see LICENSE.