Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@synap-core/cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@synap-core/cli

Connect OpenClaw to your Synap pod — sovereign knowledge infrastructure for AI agents.

npx @synap-core/cli init

What it does

synap init walks you through three paths depending on your setup:

Path	When to use
A — Existing OpenClaw	OpenClaw is already running, just connect it to Synap
B — Fresh install	No OpenClaw yet — generates config, you run `openclaw --config synap.json`
C — Managed pod	Point to your Synap cloud pod, CLI handles everything

After init, your AI agent gets structured memory (entities, relationships, full-text search, knowledge graph) via the synap OpenClaw skill.

Install

# Run once (no install needed)
npx @synap-core/cli init

# Or install globally
npm install -g @synap-core/cli
synap init

Requirements: Node.js 20+

Detailed setup for Linux servers, Docker, SSH environments, and permission issues: docs/INSTALL.md

Commands

`synap init`

Full setup wizard. Detects OpenClaw, connects to a pod, installs the skill, seeds the Agent OS workspace.

synap init

If OpenClaw is being provisioned on a managed server, setup may take a few minutes. Run synap finish once it's ready.

`synap finish`

Complete the setup after OpenClaw has started (managed pod path). Installs the skill, seeds entities, configures the intelligence service.

synap finish

Run this after synap init if prompted — it's the second half of the managed pod flow.

`synap status`

Show the health of your entire stack at a glance.

synap status

Output covers:

Account — login state, token expiry
OpenClaw — local running state, or remote provisioning state on your pod
Synap Pod — URL, health, version
Workspace Config — workspace ID, agent user, when config was saved
Intelligence Service — whether AI is provisioned
Synap Skill — whether the skill is installed in OpenClaw
Next Steps — what to do next

`synap login`

synap login                      # Opens browser
synap login --token <token>      # Headless / server environments

For servers without a browser, generate a token at synap.live/account/tokens and use --token.

Your session is kept alive automatically — as long as synap status or synap init succeeds at least once every 7 days, you won't need to re-login.

`synap logout`

Remove stored credentials.

synap logout

`synap connect`

Connect to a pod that was already provisioned (skip the full init wizard).

synap connect

`synap security-audit`

Check your OpenClaw + Synap config for common security issues (API key exposure, outdated versions, HTTPS enforcement, etc.).

synap security-audit
synap security-audit --fix    # Auto-fix what's fixable

Example output:

  ✓ Gateway bound to loopback
  ✓ Token authentication enabled
  ✗ OpenClaw version 2026.2.x — CRITICAL (9.9 CVSS)
  ✓ No plaintext credentials
  ✗ ~/.openclaw world-readable
  ✓ WebSocket origin validation
  ✓ Dangerous skill scanner
  ✓ Workspace filesystem access
  ✓ Exec approval gates

  Score: B  (2 issues, 1 critical)

`synap update`

Update the Synap skill in your OpenClaw installation to the latest version.

synap update

Configuration

The CLI stores config in ~/.synap/ (user-only, chmod 600):

File	Contents
`credentials.json`	CP auth token
`pod-config.json`	Pod URL, workspace ID, agent user ID, Hub API key

Never commit these files.

Environment variables

Variable	Default	Description
`SYNAP_CP_URL`	`https://api.synap.live`	Control plane API URL
`SYNAP_LANDING_URL`	`https://synap.live`	Landing page URL (for OAuth callback)

How the skill works

The synap OpenClaw skill gives your AI agents access to Synap's Hub Protocol:

What	How the agent uses it
Store a memory	Save a fact — keyword or semantic search
Search memories	Find relevant facts across everything stored
Create an entity	Structured object (person, task, note, project, …)
Search entities	Find by name, type, or content
Send a message	Post to any channel
Create a proposal	Propose a change for human review

Agents self-discover available entity types and views at runtime — no hardcoding.

Deployment paths

Self-hosted (free)

git clone https://github.com/synap-core/synap-backend
cd synap-backend
docker compose --profile openclaw up -d
# then:
synap init  # → "Connect to existing pod"  → http://localhost:4000

Managed pod ($15–20/mo)

Create a pod at synap.live
Run synap init → "Connect to my Synap cloud pod"
Select your pod — CLI handles provisioning

Troubleshooting

"Could not reach pod" Check that your pod URL is reachable. For self-hosted, make sure Docker Compose is up and port 4000 is accessible.

"No workspace found on this pod" The CLI auto-creates an Agent OS workspace on first connect. Re-run synap init — it's idempotent.

"OpenClaw provisioning error" (managed pod, serverIp null) Your managed pod doesn't have a registered server IP (trial pods). Install OpenClaw locally instead:

npm i -g openclaw
synap init  # → Path A

Login on a remote server (no browser)

synap login --token <your-token>
# Generate token at: https://synap.live/account/tokens

"Session expired" in synap status Run synap login again. In normal use the session auto-refreshes and you should only need to login once.

Why Synap

Structured memory: OpenClaw's MEMORY.md is flat files. Synap gives you PostgreSQL + pgvector + Typesense — entities, relationships, full-text + semantic search.
Governance: AI agent mutations go through proposals — reviewable, reversible, auditable.
Sovereign: Self-host for free. Your data stays on your infrastructure.

License

MIT