CLI command reference

All commands operate on the client your session is bound to; you don’t pass a client id. Run any command with --help for its full options.

Global flags

These work on every command:

Flag	Description
`--output`, `-o` `table\|json\|csv`	Output format. `table` on a terminal, `json`/`csv` for scripting.
`--profile`, `-p` `<name>`	Use a specific account/profile.
`--env` `prod\|staging`	Target environment (default: prod).
`--api-base` `<url>`	Override the server URL (for local development).
`--quiet`	Suppress success/info chatter (errors and data still print).
`--verbose`, `-v`	Echo HTTP requests to stderr.
`--version`	Print the CLI version.

Global flags may be placed before or after the command. Destructive commands accept --yes / -y to skip the confirmation prompt.

Environment variables

Variable	Effect
`SYNAP_API_KEY`	Authenticate with this key directly. No login, no config file. The zero-config path for CI, servers, and containers. Overrides any stored profile.
`SYNAP_PROFILE`	Default profile to use (same as `--profile`).
`SYNAP_API_BASE` / `SYNAP_ENV`	Default server / environment.

auth

Command	Description
`auth login [--profile <name>] [--no-browser]`	Browser device-pairing login. Creates or refreshes the profile’s session.
`auth activate --key <synap_...>`	Log in with an existing API key. No browser (CI/servers). For ephemeral CI, prefer the `SYNAP_API_KEY` env var (no file written).
`auth refresh`	Renew the active key before it expires. Mints a fresh key (same scopes) and revokes the old one. Must run while the key is still valid.
`auth logout`	Revoke the active key server-side and remove it locally.
`auth whoami` (alias `maximem-synap whoami`)	Show client, scopes, key expiry, and profile.
`auth list`	List all logged-in accounts (active one starred).
`auth use <profile>`	Set the active account.
`auth print-access-token`	Print the active key (for scripts/CI).

maximem-synap auth login
maximem-synap whoami
maximem-synap auth use acme

instances

Provision and manage memory instances.

Command	Description
`instances list [--status <s>] [--page <n>] [--page-size <n>]`	List instances with status, config state, and memory counts.
`instances get <id>`	Show one instance in detail.
`instances create --name <n> --relationship <r> --from-file <usecase.md> [--agent-type <t>] [--metadata <json>]`	Create an instance. `--relationship` is `b2c \| b2b \| internal \| agent_to_agent`. `--from-file` is required: the use-case markdown file the memory architecture is generated from. `--metadata` takes a JSON object.
`instances update <id> [--name <n>] [--metadata <json>]`	Rename or edit an instance. `--metadata` replaces metadata with a JSON object; the stored use-case file is kept.
`instances promote <id> --target-name <n> [--copy-mode <m>]`	Create a production sibling. `--copy-mode` is `config_only \| config_and_memories`.
`instances open [<id>] [--no-browser]`	Open the instance (or the instances list) in the dashboard.
`instances delete <id> [--yes]`	Delete an instance (typed-name confirmation unless `--yes`).

maximem-synap instances list
maximem-synap instances create --name "Support Agent" --relationship b2c --from-file ./use-case.md
maximem-synap instances get inst_a1b2c3d4

A freshly created instance generates its memory architecture (MACA) in the background and stays pending until approved in the Dashboard. instances promote requires an approved config.

api-keys

Manage the runtime API keys your agents use with the SDK.

Command	Description
`api-keys list [--instance <id>]`	List keys (metadata only, never the secret). Omit `--instance` to list every key in your client.
`api-keys create --instance <id> [--label <l>]`	Mint a key. The secret is shown once.
`api-keys get <credential-id>`	Show metadata for one key.
`api-keys rotate <credential-id> [--label <l>] [--yes]`	Mint a replacement key for the same instance, then revoke the old one.
`api-keys revoke <credential-id> [--yes]`	Revoke a key immediately.

maximem-synap api-keys create --instance inst_a1b2c3d4 --label prod
maximem-synap api-keys list --instance inst_a1b2c3d4
maximem-synap api-keys revoke <credential-id>

The plaintext key is returned only at creation. Copy it immediately and store it as SYNAP_API_KEY in your agent’s environment.

client

Inspect your client and manage its team.

Command	Description
`client get`	Show the client your session is bound to.
`client members list`	List members and their roles.
`client members invite --email <e> [--role <r>]`	Invite a member by email. `--role` is `owner \| admin \| member`. The invitee does not need a Synap account yet.
`client members update <user-id> --role <r>`	Change a member’s role.
`client members remove <user-id> [--yes]`	Remove a member.

maximem-synap client get
maximem-synap client members list
maximem-synap client members invite --email [email protected] --role member

An invite is pending until the invitee accepts it. They receive an email; if they don’t have a Synap account yet, the invite is applied when they sign up with that address. Pending invites show in both client members list and the Dashboard’s team list with state pending. An email can belong to only one client organization.

requests

Inspect request-level SDK activity: the same data as the Dashboard’s Requests view.

Command	Description
`requests list [filters]`	List SDK requests (add / search / get_all / delete) in a time window.
`requests events <correlation-id>`	Show the memory actions a single request produced.

Filters for requests list:

Flag	Description
`--since`, `-s` `<window>`	`1h \| 6h \| 12h \| 1d \| 7d \| 14d \| 30d \| 90d \| all` (default `1d`). Or use `--start`/`--end` for a custom range.
`--instance`, `-i` `<id>`	Filter to one instance.
`--type` `add\|search\|get_all\|delete`	Operation type.
`--status` `succeeded\|failed\|processing`	Outcome.
`--user`, `--agent`, `--app`, `--run`, `--request-id`	Filter by the corresponding identifier.
`--has-results`	Only requests that returned results.
`--sort` `time\|latency:asc\|desc`	Sort order (e.g. `latency:desc`).
`--watch`, `-w`	Stream new requests as they arrive (Ctrl-C to stop). `--interval <s>` sets the poll cadence.
`--page` / `--limit`	Pagination.

maximem-synap requests list --since 1h
maximem-synap requests list --since 7d --type search --status failed --sort latency:desc
maximem-synap requests list --watch          # live tail while you debug an integration

memories

Inspect stored memories (read-only; writes happen through the SDK at runtime).

Command	Description
`memories list [filters]`	List memories with the Dashboard’s filter set.
`memories get <memory-id>`	Show one memory in detail.
`memories history <memory-id>`	Show a memory’s action changelog.
`memories lineage <memory-id>`	Show a memory’s immediate lineage (enriched/superseded neighbours).

Filters for memories list:

Flag	Description
`--instance`, `-i` `<id>`	Filter to one instance.
`--search`, `-q` `<query>`	Full-text search on content.
`--type` `<t>`	`facts \| preferences \| episodes \| emotions \| temporal_events`. Plural: `facts`, not `fact`.
`--scope` `<s>`	`client \| customer \| user`.
`--entity` `<e>`	Filter by entity.
`--page` / `--limit`	Pagination.

maximem-synap memories list --instance inst_a1b2c3d4
maximem-synap memories list --type preferences --search "window seat"

privacy

Your sensitive-data controls: what gets detected, what happens to it, and who looked at it. Two things about this surface catch people out, so the CLI says them as it goes:

Saving is not turning on. privacy policy set writes a draft and changes nothing. privacy policy approve is the only command that makes a policy live.standard protects no identity. That preset leaves raw identity and contact info as “not sensitive”, so names, dates of birth and phone numbers are detected and never aliased. Only regulated protects them. privacy policy preset prints what a preset does, and which categories it leaves open, before applying it.

Command	Description
`privacy status`	Is anything actually protected right now. Start here.
`privacy policy get [--instance <id>]`	The live policy, any waiting draft, and what each category can actually be detected by.
`privacy policy set --set <category>=<setting> ...`	Save a draft. Merged onto what is already there, so changing one row never resets the others.
`privacy policy approve [--instance <id>]`	Approve the waiting draft. This is what turns a policy on.
`privacy policy preset <name>`	Set every category at once from a starting point, and turn it on. `minimal \| standard \| regulated \| store_nothing`.
`privacy policy history [--instance <id>]`	Every version, newest first, and who made it. Changes made by Synap staff are marked.
`privacy policy use-account-settings --instance <id>`	Drop an instance’s own rules so it follows the account policy again.
`privacy preview --text "..."`	Run detection over some text and see what would happen to it. Nothing sent here is stored.
`privacy report [--window-days <n>]`	What was found in your data over a window. Counts only, never values.
`privacy floor [--days <n>]`	What the floor removed. The floor applies to every client and cannot be switched off.
`privacy aliases`	How many protected values are held, by field type. Counts only.
`privacy activity list [--days <n>] [--action <a>] [--actor <a>]`	Everything that happened to your sensitive data, yours and ours.
`privacy activity export [--days <n>] [--out <file>]`	The same list as CSV, for an auditor.
`privacy reveal --label <l> --reason "..."`	Read protected values in the clear. Writes one audit row per value.
`privacy credential-grant --credential-id <id> --grant <g>`	Narrow what one of your keys receives: `full \| masked \| none`. Narrowing only.
`privacy field-types list`	The field types that can be detected, and their categories.
`privacy field-types create --key <k> --label <l> --category <c>`	Define a field type of your own. It reaches the detector without a deploy.
`privacy field-types delete <key>`	Remove a field type you defined.
`privacy suggestions list [--days <n>]`	Field types seen in your traffic that nobody has decided about.
`privacy suggestions decide <field-type> --outcome <o>`	`protect \| ignore \| undecided`.
`privacy suggestions example <field-type>`	One real occurrence, from your own data. Audited like a reveal.

Settings for --set and --exception: not_sensitive, hide_from_model, protect_at_rest, protect_fully, never_store, client_vault.

maximem-synap privacy status
maximem-synap privacy preview --text "I'm Ravi, call me on +91 98765 43210"

# Change two categories, review, then turn it on.
maximem-synap privacy policy set --set raw_identity=protect_fully --set contact_info=protect_fully
maximem-synap privacy policy get
maximem-synap privacy policy approve

# Scope a stricter policy to one instance.
maximem-synap privacy policy preset regulated --instance inst_a1b2c3d4

A reveal made through the CLI is recorded against the API key that made it, not against a person, because a key is what made the request. If you need a named human on the audit row, do it in the Dashboard.

visibility

Which instances’ memories are visible to which other instances at retrieval time. The default is shared_all: every instance of your client shares memory. Switch the default to isolated and then grant only the pairs you want.

Command	Description
`visibility get [--matrix]`	The current policy. `--matrix` renders the full viewer-by-source grid.
`visibility set-mode <shared_all\|isolated>`	Switch the default. Grants and shareable flags are preserved either way.
`visibility grant <viewer> <source>`	Let one instance read another’s memories.
`visibility revoke <viewer> <source>`	Stop it.
`visibility share <instance> --off`	Source-side opt-out: with this off, no grant anywhere makes that instance readable.
`visibility set --from-file <file.json>`	Replace the whole policy from JSON. The escape hatch.

maximem-synap visibility set-mode isolated
maximem-synap visibility grant inst_support inst_billing
maximem-synap visibility get --matrix

grant, revoke, share and set-mode read the current policy first and send its version back with the change. If somebody else edits the matrix at the same time, your command fails and writes nothing rather than overwriting theirs. Re-run it.

scoping

The scope ladder: your own hierarchy of levels, and the per-instance switch that turns nested scoping on.

Nested scoping is off by default, and every instance ships following that default. A ladder can exist, be accepted, and still be consulted by nothing. scoping ladder get reports how many of your instances actually have it on, and warns you when the answer is none.

Command	Description
`scoping explain [--user-id <u>] [--customer-id <c>] [--scope <json>]`	What a request carrying those ids would resolve to, and what it would be able to read. Creates nothing.
`scoping ladder get`	Your ladder, in your own level names, with live node counts per rung.
`scoping coverage`	How much of your data is actually filed on the ladder.
`scoping ladder propose [--instance <id>]`	A proposed ladder, with the reason for each rung. Writes nothing.
`scoping ladder apply-proposal [--commit]`	Apply the proposal. Previews unless you pass `--commit`.
`scoping ladder accept [--label <key>=<label>]`	Create a first ladder. Conflicts if one already exists.
`scoping ladder ratify [--label <key>=<label>]`	Accept the ladder as it stands, recording who agreed and when.
`scoping ladder rename --label <key>=<label>`	Rename rungs. Cosmetic: nothing moves.
`scoping ladder add-level --key <k> --label <l> --description <d> --position <n> [--commit]`	Add a rung. Previews unless you pass `--commit`.
`scoping enable <instance-id>`	Turn nested scoping on for one instance.
`scoping disable <instance-id>`	Turn it off. This beats a deployment-wide “on”.
`scoping cross-user list`	Per instance: whether one person’s memories can be read by another.
`scoping cross-user set <instance-id> --on --reason "..."`	Record that decision. A reason is required.

# What would a request for this person actually see?
maximem-synap scoping explain --customer-id acme --user-id u_44 --instance inst_a1b2c3d4

maximem-synap scoping ladder get
maximem-synap scoping ladder add-level --key practice --label Practice \
  --description "A physical clinic under a customer." --position 1

add-level and apply-proposal preview by default because inserting a rung re-homes every node beneath it. The preview reports how many nodes would move, and --commit sends that number back with the write, so a commit is refused if the tree changed in between.

billing

Billing controls for your client. Today that is overages: whether requests keep working after a paid plan’s credits run out, with the extra usage billed per 1,000 credits at your plan’s rate. Overages are off by default. See Pricing & Credits for how they are billed.

Command	Description
`billing overages get`	Whether overages are on, whether they can be turned on (and if not, why), your plan’s overage rate, the card they would be charged to (brand, last four digits, expiry), and who last changed the setting and when.
`billing overages set --allow [--yes]`	Turn overages on. Shows the rate and the card, then asks you to confirm unless you pass `--yes`. Owner only.
`billing overages set --disallow`	Turn overages off. Requests stop when credits run out. Owner only; no confirmation.

maximem-synap billing overages get
maximem-synap billing overages set --allow
maximem-synap billing overages get --output json    # includes can_edit, for scripts

Only the client owner can change overages. A CLI key acts with the role of the person who approved its login, so a key approved by an admin or member can read the setting and gets a permission error from set. For overages that role is checked when you run the command: if the person who approved the key is no longer the owner, the key cannot change the setting either. billing overages get reports can_edit. If an owner’s key reports can_edit: false, run maximem-synap auth login again.Turning overages on needs a chargeable card: the default card on your subscription, or else the default card on your billing account, and not expired. Other saved cards do not count. The plan must be Starter, Pro or Scale with an active subscription. If any of that is missing, set --allow fails, writes nothing, and says what to fix. Add or update the card in the Dashboard under Credits & Usage → Plan & billing.

Synap turns overages off by itself when the card is removed or expires, or the subscription is cancelled, and emails every member of your client. billing overages get then shows Synap, with the reason, as the last change.

config

Local CLI settings for the active profile.

Command	Description
`config get`	Show the active profile’s settings.
`config set <key> <value>`	Set a setting (e.g. `api_base`).
`config path`	Print the path of the config file.

maximem-synap config get
maximem-synap config path

usage

Aggregate usage for your client: API calls, LLM tokens, memories stored.

Command	Description
`usage [--period <p>]`	Usage summary. `--period` is `all \| 1d \| 7d \| 30d \| 90d \| custom` (default `30d`); use `--start`/`--end` for a custom range.

maximem-synap usage --period 7d
maximem-synap usage --start 2026-01-01 --end 2026-01-31

doctor

Diagnose your setup: CLI version, Python, config, auth, server connectivity, key expiry, and whether anything is actually being protected.

maximem-synap doctor

Use in CI

No browser is available in CI, so authenticate with a key instead of auth login:

export SYNAP_API_KEY=synap_...            # from `api-keys create`
maximem-synap instances list --output json

SYNAP_API_KEY overrides any stored profile and writes nothing to disk, so it’s safe for ephemeral runners.

Dashboard

CLI

Resources

Changelog

Global flags

Environment variables

auth

instances

api-keys

client

requests

memories

privacy

visibility

scoping

billing

config

usage

doctor

Use in CI

​Global flags

​Environment variables

​auth

​instances

​api-keys

​client

​requests

​memories

​privacy

​visibility

​scoping

​billing

​config

​usage

​doctor

​Use in CI

Global flags

Environment variables

auth

instances

api-keys

client

requests

memories

privacy

visibility

scoping

billing

config

usage

doctor

Use in CI