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> [--agent-type <t>] [--description <d>] [--metadata <json>] [--from-file <usecase.md>]`	Create an instance. `--relationship` is `b2c \| b2b \| internal \| agent_to_agent`. `--metadata` takes a JSON object; `--from-file` seeds the use-case from a markdown file.
`instances update <id> [--name <n>] [--description <d>] [--metadata <json>]`	Rename or edit an instance. `--metadata` replaces metadata with a JSON object.
`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
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. `--role` is `owner \| admin \| member`.
`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

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>`	Memory type (e.g. `facts`, `preferences`, `episodes`).
`--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"

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, and key expiry.

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

config

usage

doctor

Use in CI

​Global flags

​Environment variables

​auth

​instances

​api-keys

​client

​requests

​memories

​config

​usage

​doctor

​Use in CI

Global flags

Environment variables

auth

instances

api-keys

client

requests

memories

config

usage

doctor

Use in CI