> ## Documentation Index > Fetch the complete documentation index at: https://docs.maximem.ai/llms.txt > Use this file to discover all available pages before exploring further. # CLI command reference > Every maximem-synap command and flag — auth, instances, api-keys, client, requests, memories, and config. 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` `` | Use a specific account/profile. | | `--env` `prod\|staging` | Target environment (default: prod). | | `--api-base` `` | 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 Log in, log out, and switch accounts. | Command | Description | | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `auth login [--profile ] [--no-browser]` | Browser device-pairing login. Creates or refreshes the profile's session. | | `auth activate --key ` | 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 ` | Set the active account. | | `auth print-access-token` | Print the active key (for scripts/CI). | ```bash theme={null} maximem-synap auth login maximem-synap whoami maximem-synap auth use acme ``` ## instances Provision and manage memory instances. | Command | Description | | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `instances list [--status ] [--page ] [--page-size ]` | List instances with status, config state, and memory counts. | | `instances get ` | Show one instance in detail. | | `instances create --name --relationship [--agent-type ] [--description ] [--metadata ] [--from-file ]` | 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 [--name ] [--description ] [--metadata ]` | Rename or edit an instance. `--metadata` replaces metadata with a JSON object. | | `instances promote --target-name [--copy-mode ]` | Create a production sibling. `--copy-mode` is `config_only \| config_and_memories`. | | `instances open [] [--no-browser]` | Open the instance (or the instances list) in the dashboard. | | `instances delete [--yes]` | Delete an instance (typed-name confirmation unless `--yes`). | ```bash theme={null} 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](/dashboard/overview). `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 ]` | List keys (metadata only — never the secret). Omit `--instance` to list every key in your client. | | `api-keys create --instance [--label ]` | Mint a key. The secret is shown **once**. | | `api-keys get ` | Show metadata for one key. | | `api-keys rotate [--label ] [--yes]` | Mint a replacement key for the same instance, then revoke the old one. | | `api-keys revoke [--yes]` | Revoke a key immediately. | ```bash theme={null} maximem-synap api-keys create --instance inst_a1b2c3d4 --label prod maximem-synap api-keys list --instance inst_a1b2c3d4 maximem-synap api-keys revoke ``` 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 [--role ]` | Invite a member. `--role` is `owner \| admin \| member`. | | `client members update --role ` | Change a member's role. | | `client members remove [--yes]` | Remove a member. | ```bash theme={null} maximem-synap client get maximem-synap client members list maximem-synap client members invite --email dev@acme.com --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 ` | Show the memory actions a single request produced. | Filters for `requests list`: | Flag | Description | | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `--since`, `-s` `` | `1h \| 6h \| 12h \| 1d \| 7d \| 14d \| 30d \| 90d \| all` (default `1d`). Or use `--start`/`--end` for a custom range. | | `--instance`, `-i` `` | 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 ` sets the poll cadence. | | `--page` / `--limit` | Pagination. | ```bash theme={null} 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 ` | Show one memory in detail. | | `memories history ` | Show a memory's action changelog. | | `memories lineage ` | Show a memory's immediate lineage (enriched/superseded neighbours). | Filters for `memories list`: | Flag | Description | | -------------------------- | ------------------------------------------------------ | | `--instance`, `-i` `` | Filter to one instance. | | `--search`, `-q` `` | Full-text search on content. | | `--type` `` | Memory type (e.g. `facts`, `preferences`, `episodes`). | | `--scope` `` | `client \| customer \| user`. | | `--entity` `` | Filter by entity. | | `--page` / `--limit` | Pagination. | ```bash theme={null} 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 ` | Set a setting (e.g. `api_base`). | | `config path` | Print the path of the config file. | ```bash theme={null} maximem-synap config get maximem-synap config path ``` ## usage Aggregate usage for your client — API calls, LLM tokens, memories stored. | Command | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `usage [--period

]` | Usage summary. `--period` is `all \| 1d \| 7d \| 30d \| 90d \| custom` (default `30d`); use `--start`/`--end` for a custom range. | ```bash theme={null} 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. ```bash theme={null} maximem-synap doctor ``` ## Use in CI No browser is available in CI, so authenticate with a key instead of `auth login`: ```bash theme={null} 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.