maximem-synap-cli 0.3.5__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. maximem_synap_cli-0.3.5/PKG-INFO +178 -0
  2. maximem_synap_cli-0.3.5/maximem_synap_cli.egg-info/PKG-INFO +178 -0
  3. maximem_synap_cli-0.3.5/maximem_synap_cli.egg-info/SOURCES.txt +32 -0
  4. maximem_synap_cli-0.3.5/maximem_synap_cli.egg-info/dependency_links.txt +1 -0
  5. maximem_synap_cli-0.3.5/maximem_synap_cli.egg-info/entry_points.txt +3 -0
  6. maximem_synap_cli-0.3.5/maximem_synap_cli.egg-info/requires.txt +3 -0
  7. maximem_synap_cli-0.3.5/maximem_synap_cli.egg-info/top_level.txt +1 -0
  8. maximem_synap_cli-0.3.5/pyproject.toml +59 -0
  9. maximem_synap_cli-0.3.5/setup.cfg +4 -0
  10. maximem_synap_cli-0.3.5/synap/cli/README.md +157 -0
  11. maximem_synap_cli-0.3.5/synap/cli/__init__.py +11 -0
  12. maximem_synap_cli-0.3.5/synap/cli/__main__.py +157 -0
  13. maximem_synap_cli-0.3.5/synap/cli/action_rows.py +36 -0
  14. maximem_synap_cli-0.3.5/synap/cli/api.py +402 -0
  15. maximem_synap_cli-0.3.5/synap/cli/app.py +362 -0
  16. maximem_synap_cli-0.3.5/synap/cli/commands/__init__.py +1 -0
  17. maximem_synap_cli-0.3.5/synap/cli/commands/api_keys.py +396 -0
  18. maximem_synap_cli-0.3.5/synap/cli/commands/auth.py +1277 -0
  19. maximem_synap_cli-0.3.5/synap/cli/commands/billing.py +342 -0
  20. maximem_synap_cli-0.3.5/synap/cli/commands/client.py +92 -0
  21. maximem_synap_cli-0.3.5/synap/cli/commands/config_cmd.py +56 -0
  22. maximem_synap_cli-0.3.5/synap/cli/commands/instances.py +595 -0
  23. maximem_synap_cli-0.3.5/synap/cli/commands/memories.py +148 -0
  24. maximem_synap_cli-0.3.5/synap/cli/commands/onboard.py +220 -0
  25. maximem_synap_cli-0.3.5/synap/cli/commands/privacy.py +677 -0
  26. maximem_synap_cli-0.3.5/synap/cli/commands/requests.py +181 -0
  27. maximem_synap_cli-0.3.5/synap/cli/commands/scoping.py +471 -0
  28. maximem_synap_cli-0.3.5/synap/cli/commands/skill.py +100 -0
  29. maximem_synap_cli-0.3.5/synap/cli/commands/visibility.py +302 -0
  30. maximem_synap_cli-0.3.5/synap/cli/config.py +250 -0
  31. maximem_synap_cli-0.3.5/synap/cli/envfile.py +232 -0
  32. maximem_synap_cli-0.3.5/synap/cli/interactive.py +94 -0
  33. maximem_synap_cli-0.3.5/synap/cli/render.py +169 -0
  34. maximem_synap_cli-0.3.5/synap/cli/validate.py +67 -0
@@ -0,0 +1,178 @@
1
+ Metadata-Version: 2.4
2
+ Name: maximem-synap-cli
3
+ Version: 0.3.5
4
+ Summary: maximem-synap — provision and operate Synap from your terminal
5
+ Author-email: Maximem <hello@maximem.ai>
6
+ License: Proprietary
7
+ Project-URL: Homepage, https://maximem.ai
8
+ Project-URL: Documentation, https://docs.maximem.ai
9
+ Keywords: synap,maximem,memory,cli,agents
10
+ Classifier: Environment :: Console
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Requires-Python: >=3.10
17
+ Description-Content-Type: text/markdown
18
+ Requires-Dist: typer>=0.12
19
+ Requires-Dist: httpx>=0.27
20
+ Requires-Dist: rich>=13
21
+
22
+ # maximem-synap
23
+
24
+ The **developer CLI** for [Synap](https://maximem.ai) — provision and operate
25
+ your Synap account from the terminal.
26
+
27
+ > **CLI vs SDK.** This CLI is the *control plane* for developers. It is **not**
28
+ > the runtime SDK. Your agents/apps integrate Synap with `@maximem/synap-js-sdk`
29
+ > or the Python SDK (`recall`, `save_memories`, `context`). The CLI is for
30
+ > humans: logging in, creating instances, minting keys, managing your team.
31
+
32
+ ## Install
33
+
34
+ ```bash
35
+ npx @maximem/synap-cli@latest auth login
36
+ ```
37
+
38
+ That bootstraps the Python CLI onto your PATH (`~/.local/bin/maximem-synap`) and
39
+ then runs it — the gcloud model: install a package, then `auth login`.
40
+
41
+ Requires Python 3.10+ on the host (the CLI itself is Python; the npm package is
42
+ just the installer).
43
+
44
+ > **npx is the only supported channel right now.** Homebrew,
45
+ > `curl | sh`, and `pipx install maximem-synap-cli` all resolve the CLI from
46
+ > PyPI, and it has not been published there yet — those channels will fail. The
47
+ > npm package bundles the wheel, which is why it works. See
48
+ > [`packaging/README.md`](../../packaging/README.md) for the publish checklist.
49
+
50
+ ## Log in (browser, like `gcloud auth login`)
51
+
52
+ ```bash
53
+ maximem-synap auth login
54
+ ```
55
+
56
+ Prints a short code and opens your browser. Confirm the code, pick your client,
57
+ approve — and you're logged in. Works over SSH too (just open the printed URL).
58
+
59
+ ```bash
60
+ maximem-synap whoami # which account am I? Also shows user_context_isolation
61
+ maximem-synap auth list # profile, workspace, environment, active marker
62
+ ```
63
+
64
+ `whoami` shows `user_context_isolation` as `b2c` or `b2b` so you can tell them apart without a
65
+ second call. It comes from the server's `/whoami`; if that lacks it, it is read from the one
66
+ instance the key is scoped to, and otherwise it says `unknown` (never a guess).
67
+
68
+ ### Profiles: logins never overwrite another workspace
69
+
70
+ - `auth login --code` names the profile after the workspace (lowercase `a-z0-9-`, at most 30
71
+ characters; `-2`, `-3` on a name clash with another workspace). Logging in again to the same
72
+ workspace and environment updates that profile in place. A different workspace or environment
73
+ always gets its own profile; the old one is left byte for byte as it was.
74
+ - `--profile NAME` always means NAME. If NAME holds a different workspace or environment the
75
+ login is refused with exit 6 (`profile_conflict`) unless you pass `--force`.
76
+ - A one-time-code login (the agent flow) always becomes the active profile, so later commands
77
+ need no `--profile`. If another profile was active, the CLI says so and how to switch back
78
+ (`maximem-synap auth use <name>`); `--output json` carries `previous_active_profile`.
79
+ - Browser login is more conservative: it becomes active only if nothing was active or the active
80
+ profile is the same workspace. Otherwise it prints `Your active profile is still <other>`.
81
+ - Long-running commands (`instances wait`) capture the profile and key once at start, so a login
82
+ that rewrites the config mid-run does not change who they talk to.
83
+
84
+ ## What you can do
85
+
86
+ ```bash
87
+ maximem-synap instances list
88
+ maximem-synap instances create --name "Acme Support" --relationship b2c
89
+ maximem-synap api-keys create --instance <id> --label prod # shown once
90
+ maximem-synap client members list
91
+ maximem-synap --help
92
+ ```
93
+
94
+ Use `--output json` (or its alias `--json`) on any command for scripting, and
95
+ `--profile <name>` to keep multiple accounts side by side. Global flags (`--output`,
96
+ `--json`, `--profile`, `--env`, `--api-base`, `--verbose`) may be placed before or after the
97
+ command. `--json` together with `--output table|csv` is a usage error (exit 2).
98
+
99
+ ## CI / non-interactive
100
+
101
+ No browser? Authenticate with a key instead of `auth login`:
102
+
103
+ ```bash
104
+ export SYNAP_API_KEY=synap_... # from `maximem-synap api-keys create`
105
+ maximem-synap instances list --output json
106
+ ```
107
+
108
+ `SYNAP_API_KEY` overrides any profile and writes nothing to disk. Or persist a key
109
+ with `maximem-synap auth activate --key synap_...`.
110
+
111
+ ## Agent-driven setup (no browser, no prompts)
112
+
113
+ Everything a coding agent needs runs without a TTY or a browser:
114
+
115
+ ```bash
116
+ maximem-synap auth login --code syn_ob_XXXX-XXXX-XXXX # or SYNAP_ONBOARDING_CODE=...
117
+ maximem-synap onboard status -o json # where is setup up to?
118
+ maximem-synap instances template --output-file usecase.md # the use-case template
119
+ maximem-synap instances create --name "Acme" --relationship <b2c|b2b|internal|agent_to_agent> --from-file usecase.md
120
+ # or: ... --from-stdin < usecase.md (--relationship is always required: no default, asked of the human)
121
+ maximem-synap api-keys create -i <id> --write-env # key goes to ./.env, never printed
122
+ maximem-synap api-keys rotate <key-id> --yes --write-env # new key to ./.env, old one revoked, never printed
123
+ maximem-synap instances wait <id> --timeout 1200 # blocks until the memory build is done
124
+ maximem-synap onboard report integrating in_progress # steps: use_case_drafted, use_case_approved,
125
+ # integrating, env_written
126
+ maximem-synap onboard ask "Is this B2C or B2B?" # tell the dashboard you are waiting; --clear to clear
127
+ maximem-synap skill install [--agent claude-code|cursor|codex|auto]
128
+ ```
129
+
130
+ Onboarding codes work once, expire after 10 minutes and are accepted in any letter case; copy a
131
+ fresh prompt from the dashboard if one is rejected. The code is never printed or logged. Without
132
+ `--code` (or `SYNAP_ONBOARDING_CODE`), `auth login` under `--non-interactive` exits 3 instead of
133
+ opening a browser. Onboarding keys last exactly 7 days and cannot be renewed (`auth refresh` answers 403 `onboarding_key_not_refreshable`, exit 3); after expiry a fresh prompt with a new code is needed. `whoami` only warns in the last 24 hours.
134
+
135
+ `--write-env [PATH]` (default `./.env`) writes `SYNAP_API_KEY` and `SYNAP_INSTANCE_ID`, and for a
136
+ non-production environment also `SYNAP_BASE_URL`, `SYNAP_GRPC_HOST`, `SYNAP_GRPC_PORT` and
137
+ `SYNAP_GRPC_USE_TLS`. It creates the file with mode `0600` and updates existing lines in place: a
138
+ variable already there (also as `export NAME=...` or with a quoted value, even if added by hand
139
+ and repeated) is replaced and kept exactly once, never duplicated. It also adds the file to `.gitignore`, and prints only a masked key
140
+ (`synap_…abcd`) and the path. An existing file keeps its mode, CRLF line endings and `export ` prefixes;
141
+ the gitignore check understands patterns and `!` negations. `api-keys rotate` takes the same flags. `--write-env PATH` is shorthand for `--write-env --env-file PATH`.
142
+
143
+ `instances wait` prints progress on stderr and one JSON object on stdout. If the configuration is
144
+ waiting for review by Synap it exits 1 at once instead of waiting for the timeout.
145
+
146
+ If `SYNAP_API_KEY` holds a runtime key (for example you sourced the project `.env`), management
147
+ calls return 401/403 and the CLI says so; run `env -u SYNAP_API_KEY maximem-synap ...`.
148
+
149
+ ### `--non-interactive`
150
+
151
+ Global flag, also on automatically when stdin is not a TTY or `SYNAP_NON_INTERACTIVE=1`
152
+ (`SYNAP_NON_INTERACTIVE=0` forces prompts back on). A command that would ask a question
153
+ fails instead, naming the flag that answers it (for example `--yes`).
154
+
155
+ ### Exit codes and JSON errors
156
+
157
+ | Code | Meaning |
158
+ |---|---|
159
+ | 0 | ok |
160
+ | 1 | generic error (also: `instances wait` build failed) |
161
+ | 2 | usage / invalid argument / confirmation needed |
162
+ | 3 | auth: not logged in, expired or invalid key or code |
163
+ | 4 | not found |
164
+ | 5 | permission / missing scope |
165
+ | 6 | conflict |
166
+ | 7 | timeout (request or `instances wait`) |
167
+ | 8 | server error or network failure |
168
+
169
+ With `--output json`, errors go to stderr as
170
+ `{"error": {"code": "<snake_case>", "message": "...", "exit_code": N, "hint": "..."}}`.
171
+ When the server sent a structured error body (for example the credits needed and available on a 402, code `insufficient_credits`, exit 1), it is passed through as `error.details`.
172
+ In table mode they stay plain text (a `Hint:` line is added when there is one).
173
+
174
+ ## Config
175
+
176
+ Credentials live in `~/.config/synap/config.json` (mode `0600`). One key per
177
+ profile, bound to one client. `maximem-synap auth logout` revokes server-side and
178
+ removes it locally.
@@ -0,0 +1,178 @@
1
+ Metadata-Version: 2.4
2
+ Name: maximem-synap-cli
3
+ Version: 0.3.5
4
+ Summary: maximem-synap — provision and operate Synap from your terminal
5
+ Author-email: Maximem <hello@maximem.ai>
6
+ License: Proprietary
7
+ Project-URL: Homepage, https://maximem.ai
8
+ Project-URL: Documentation, https://docs.maximem.ai
9
+ Keywords: synap,maximem,memory,cli,agents
10
+ Classifier: Environment :: Console
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Requires-Python: >=3.10
17
+ Description-Content-Type: text/markdown
18
+ Requires-Dist: typer>=0.12
19
+ Requires-Dist: httpx>=0.27
20
+ Requires-Dist: rich>=13
21
+
22
+ # maximem-synap
23
+
24
+ The **developer CLI** for [Synap](https://maximem.ai) — provision and operate
25
+ your Synap account from the terminal.
26
+
27
+ > **CLI vs SDK.** This CLI is the *control plane* for developers. It is **not**
28
+ > the runtime SDK. Your agents/apps integrate Synap with `@maximem/synap-js-sdk`
29
+ > or the Python SDK (`recall`, `save_memories`, `context`). The CLI is for
30
+ > humans: logging in, creating instances, minting keys, managing your team.
31
+
32
+ ## Install
33
+
34
+ ```bash
35
+ npx @maximem/synap-cli@latest auth login
36
+ ```
37
+
38
+ That bootstraps the Python CLI onto your PATH (`~/.local/bin/maximem-synap`) and
39
+ then runs it — the gcloud model: install a package, then `auth login`.
40
+
41
+ Requires Python 3.10+ on the host (the CLI itself is Python; the npm package is
42
+ just the installer).
43
+
44
+ > **npx is the only supported channel right now.** Homebrew,
45
+ > `curl | sh`, and `pipx install maximem-synap-cli` all resolve the CLI from
46
+ > PyPI, and it has not been published there yet — those channels will fail. The
47
+ > npm package bundles the wheel, which is why it works. See
48
+ > [`packaging/README.md`](../../packaging/README.md) for the publish checklist.
49
+
50
+ ## Log in (browser, like `gcloud auth login`)
51
+
52
+ ```bash
53
+ maximem-synap auth login
54
+ ```
55
+
56
+ Prints a short code and opens your browser. Confirm the code, pick your client,
57
+ approve — and you're logged in. Works over SSH too (just open the printed URL).
58
+
59
+ ```bash
60
+ maximem-synap whoami # which account am I? Also shows user_context_isolation
61
+ maximem-synap auth list # profile, workspace, environment, active marker
62
+ ```
63
+
64
+ `whoami` shows `user_context_isolation` as `b2c` or `b2b` so you can tell them apart without a
65
+ second call. It comes from the server's `/whoami`; if that lacks it, it is read from the one
66
+ instance the key is scoped to, and otherwise it says `unknown` (never a guess).
67
+
68
+ ### Profiles: logins never overwrite another workspace
69
+
70
+ - `auth login --code` names the profile after the workspace (lowercase `a-z0-9-`, at most 30
71
+ characters; `-2`, `-3` on a name clash with another workspace). Logging in again to the same
72
+ workspace and environment updates that profile in place. A different workspace or environment
73
+ always gets its own profile; the old one is left byte for byte as it was.
74
+ - `--profile NAME` always means NAME. If NAME holds a different workspace or environment the
75
+ login is refused with exit 6 (`profile_conflict`) unless you pass `--force`.
76
+ - A one-time-code login (the agent flow) always becomes the active profile, so later commands
77
+ need no `--profile`. If another profile was active, the CLI says so and how to switch back
78
+ (`maximem-synap auth use <name>`); `--output json` carries `previous_active_profile`.
79
+ - Browser login is more conservative: it becomes active only if nothing was active or the active
80
+ profile is the same workspace. Otherwise it prints `Your active profile is still <other>`.
81
+ - Long-running commands (`instances wait`) capture the profile and key once at start, so a login
82
+ that rewrites the config mid-run does not change who they talk to.
83
+
84
+ ## What you can do
85
+
86
+ ```bash
87
+ maximem-synap instances list
88
+ maximem-synap instances create --name "Acme Support" --relationship b2c
89
+ maximem-synap api-keys create --instance <id> --label prod # shown once
90
+ maximem-synap client members list
91
+ maximem-synap --help
92
+ ```
93
+
94
+ Use `--output json` (or its alias `--json`) on any command for scripting, and
95
+ `--profile <name>` to keep multiple accounts side by side. Global flags (`--output`,
96
+ `--json`, `--profile`, `--env`, `--api-base`, `--verbose`) may be placed before or after the
97
+ command. `--json` together with `--output table|csv` is a usage error (exit 2).
98
+
99
+ ## CI / non-interactive
100
+
101
+ No browser? Authenticate with a key instead of `auth login`:
102
+
103
+ ```bash
104
+ export SYNAP_API_KEY=synap_... # from `maximem-synap api-keys create`
105
+ maximem-synap instances list --output json
106
+ ```
107
+
108
+ `SYNAP_API_KEY` overrides any profile and writes nothing to disk. Or persist a key
109
+ with `maximem-synap auth activate --key synap_...`.
110
+
111
+ ## Agent-driven setup (no browser, no prompts)
112
+
113
+ Everything a coding agent needs runs without a TTY or a browser:
114
+
115
+ ```bash
116
+ maximem-synap auth login --code syn_ob_XXXX-XXXX-XXXX # or SYNAP_ONBOARDING_CODE=...
117
+ maximem-synap onboard status -o json # where is setup up to?
118
+ maximem-synap instances template --output-file usecase.md # the use-case template
119
+ maximem-synap instances create --name "Acme" --relationship <b2c|b2b|internal|agent_to_agent> --from-file usecase.md
120
+ # or: ... --from-stdin < usecase.md (--relationship is always required: no default, asked of the human)
121
+ maximem-synap api-keys create -i <id> --write-env # key goes to ./.env, never printed
122
+ maximem-synap api-keys rotate <key-id> --yes --write-env # new key to ./.env, old one revoked, never printed
123
+ maximem-synap instances wait <id> --timeout 1200 # blocks until the memory build is done
124
+ maximem-synap onboard report integrating in_progress # steps: use_case_drafted, use_case_approved,
125
+ # integrating, env_written
126
+ maximem-synap onboard ask "Is this B2C or B2B?" # tell the dashboard you are waiting; --clear to clear
127
+ maximem-synap skill install [--agent claude-code|cursor|codex|auto]
128
+ ```
129
+
130
+ Onboarding codes work once, expire after 10 minutes and are accepted in any letter case; copy a
131
+ fresh prompt from the dashboard if one is rejected. The code is never printed or logged. Without
132
+ `--code` (or `SYNAP_ONBOARDING_CODE`), `auth login` under `--non-interactive` exits 3 instead of
133
+ opening a browser. Onboarding keys last exactly 7 days and cannot be renewed (`auth refresh` answers 403 `onboarding_key_not_refreshable`, exit 3); after expiry a fresh prompt with a new code is needed. `whoami` only warns in the last 24 hours.
134
+
135
+ `--write-env [PATH]` (default `./.env`) writes `SYNAP_API_KEY` and `SYNAP_INSTANCE_ID`, and for a
136
+ non-production environment also `SYNAP_BASE_URL`, `SYNAP_GRPC_HOST`, `SYNAP_GRPC_PORT` and
137
+ `SYNAP_GRPC_USE_TLS`. It creates the file with mode `0600` and updates existing lines in place: a
138
+ variable already there (also as `export NAME=...` or with a quoted value, even if added by hand
139
+ and repeated) is replaced and kept exactly once, never duplicated. It also adds the file to `.gitignore`, and prints only a masked key
140
+ (`synap_…abcd`) and the path. An existing file keeps its mode, CRLF line endings and `export ` prefixes;
141
+ the gitignore check understands patterns and `!` negations. `api-keys rotate` takes the same flags. `--write-env PATH` is shorthand for `--write-env --env-file PATH`.
142
+
143
+ `instances wait` prints progress on stderr and one JSON object on stdout. If the configuration is
144
+ waiting for review by Synap it exits 1 at once instead of waiting for the timeout.
145
+
146
+ If `SYNAP_API_KEY` holds a runtime key (for example you sourced the project `.env`), management
147
+ calls return 401/403 and the CLI says so; run `env -u SYNAP_API_KEY maximem-synap ...`.
148
+
149
+ ### `--non-interactive`
150
+
151
+ Global flag, also on automatically when stdin is not a TTY or `SYNAP_NON_INTERACTIVE=1`
152
+ (`SYNAP_NON_INTERACTIVE=0` forces prompts back on). A command that would ask a question
153
+ fails instead, naming the flag that answers it (for example `--yes`).
154
+
155
+ ### Exit codes and JSON errors
156
+
157
+ | Code | Meaning |
158
+ |---|---|
159
+ | 0 | ok |
160
+ | 1 | generic error (also: `instances wait` build failed) |
161
+ | 2 | usage / invalid argument / confirmation needed |
162
+ | 3 | auth: not logged in, expired or invalid key or code |
163
+ | 4 | not found |
164
+ | 5 | permission / missing scope |
165
+ | 6 | conflict |
166
+ | 7 | timeout (request or `instances wait`) |
167
+ | 8 | server error or network failure |
168
+
169
+ With `--output json`, errors go to stderr as
170
+ `{"error": {"code": "<snake_case>", "message": "...", "exit_code": N, "hint": "..."}}`.
171
+ When the server sent a structured error body (for example the credits needed and available on a 402, code `insufficient_credits`, exit 1), it is passed through as `error.details`.
172
+ In table mode they stay plain text (a `Hint:` line is added when there is one).
173
+
174
+ ## Config
175
+
176
+ Credentials live in `~/.config/synap/config.json` (mode `0600`). One key per
177
+ profile, bound to one client. `maximem-synap auth logout` revokes server-side and
178
+ removes it locally.
@@ -0,0 +1,32 @@
1
+ pyproject.toml
2
+ maximem_synap_cli.egg-info/PKG-INFO
3
+ maximem_synap_cli.egg-info/SOURCES.txt
4
+ maximem_synap_cli.egg-info/dependency_links.txt
5
+ maximem_synap_cli.egg-info/entry_points.txt
6
+ maximem_synap_cli.egg-info/requires.txt
7
+ maximem_synap_cli.egg-info/top_level.txt
8
+ synap/cli/README.md
9
+ synap/cli/__init__.py
10
+ synap/cli/__main__.py
11
+ synap/cli/action_rows.py
12
+ synap/cli/api.py
13
+ synap/cli/app.py
14
+ synap/cli/config.py
15
+ synap/cli/envfile.py
16
+ synap/cli/interactive.py
17
+ synap/cli/render.py
18
+ synap/cli/validate.py
19
+ synap/cli/commands/__init__.py
20
+ synap/cli/commands/api_keys.py
21
+ synap/cli/commands/auth.py
22
+ synap/cli/commands/billing.py
23
+ synap/cli/commands/client.py
24
+ synap/cli/commands/config_cmd.py
25
+ synap/cli/commands/instances.py
26
+ synap/cli/commands/memories.py
27
+ synap/cli/commands/onboard.py
28
+ synap/cli/commands/privacy.py
29
+ synap/cli/commands/requests.py
30
+ synap/cli/commands/scoping.py
31
+ synap/cli/commands/skill.py
32
+ synap/cli/commands/visibility.py
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ maximem-synap = synap.cli.__main__:main
3
+ synap = synap.cli.__main__:main
@@ -0,0 +1,3 @@
1
+ typer>=0.12
2
+ httpx>=0.27
3
+ rich>=13
@@ -0,0 +1,59 @@
1
+ # Packaging for the `maximem-synap` developer CLI ONLY.
2
+ #
3
+ # This is the DEVELOPER control-plane tool — distinct from the runtime SDKs
4
+ # (`@maximem/synap-js-sdk`, the Python SDK) that customer agents import to *use*
5
+ # Synap. The CLI is for provisioning/operating Synap from a terminal.
6
+ #
7
+ # The Synap server is run from source via PYTHONPATH (see scripts/synap-local.sh)
8
+ # and is intentionally NOT packaged here. This pyproject exposes only the
9
+ # dependency-light `maximem-synap` console script. Install with any of:
10
+ #
11
+ # pipx install maximem-synap-cli # Python devs (recommended)
12
+ # brew install maximem-ai/tap/maximem-synap
13
+ # curl -fsSL https://get.maximem.ai/synap | sh
14
+ # npx @maximem/synap-cli # JS devs (bootstraps the Python CLI)
15
+ #
16
+ # Local dev: `pip install -e .` registers `maximem-synap` (+ short `synap`).
17
+
18
+ [build-system]
19
+ requires = ["setuptools>=61"]
20
+ build-backend = "setuptools.build_meta"
21
+
22
+ [project]
23
+ # Distribution name is `maximem-synap-cli` (NOT `maximem-synap`): the PyPI name
24
+ # `maximem-synap` belongs to the runtime *SDK*. This is the control-plane CLI —
25
+ # a separate package. The console command it installs is still `maximem-synap`.
26
+ name = "maximem-synap-cli"
27
+ version = "0.3.5"
28
+ description = "maximem-synap — provision and operate Synap from your terminal"
29
+ readme = "synap/cli/README.md"
30
+ requires-python = ">=3.10"
31
+ license = { text = "Proprietary" }
32
+ authors = [{ name = "Maximem", email = "hello@maximem.ai" }]
33
+ keywords = ["synap", "maximem", "memory", "cli", "agents"]
34
+ dependencies = [
35
+ "typer>=0.12",
36
+ "httpx>=0.27",
37
+ "rich>=13",
38
+ ]
39
+ classifiers = [
40
+ "Environment :: Console",
41
+ "Intended Audience :: Developers",
42
+ "Programming Language :: Python :: 3",
43
+ "Programming Language :: Python :: 3.10",
44
+ "Programming Language :: Python :: 3.11",
45
+ "Programming Language :: Python :: 3.12",
46
+ ]
47
+
48
+ [project.urls]
49
+ Homepage = "https://maximem.ai"
50
+ Documentation = "https://docs.maximem.ai"
51
+
52
+ [project.scripts]
53
+ maximem-synap = "synap.cli.__main__:main"
54
+ synap = "synap.cli.__main__:main"
55
+
56
+ [tool.setuptools]
57
+ # Explicit, minimal package set so an install never scans the whole server tree.
58
+ # `synap` (empty __init__) is listed so the namespace resolves.
59
+ packages = ["synap", "synap.cli", "synap.cli.commands"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,157 @@
1
+ # maximem-synap
2
+
3
+ The **developer CLI** for [Synap](https://maximem.ai) — provision and operate
4
+ your Synap account from the terminal.
5
+
6
+ > **CLI vs SDK.** This CLI is the *control plane* for developers. It is **not**
7
+ > the runtime SDK. Your agents/apps integrate Synap with `@maximem/synap-js-sdk`
8
+ > or the Python SDK (`recall`, `save_memories`, `context`). The CLI is for
9
+ > humans: logging in, creating instances, minting keys, managing your team.
10
+
11
+ ## Install
12
+
13
+ ```bash
14
+ npx @maximem/synap-cli@latest auth login
15
+ ```
16
+
17
+ That bootstraps the Python CLI onto your PATH (`~/.local/bin/maximem-synap`) and
18
+ then runs it — the gcloud model: install a package, then `auth login`.
19
+
20
+ Requires Python 3.10+ on the host (the CLI itself is Python; the npm package is
21
+ just the installer).
22
+
23
+ > **npx is the only supported channel right now.** Homebrew,
24
+ > `curl | sh`, and `pipx install maximem-synap-cli` all resolve the CLI from
25
+ > PyPI, and it has not been published there yet — those channels will fail. The
26
+ > npm package bundles the wheel, which is why it works. See
27
+ > [`packaging/README.md`](../../packaging/README.md) for the publish checklist.
28
+
29
+ ## Log in (browser, like `gcloud auth login`)
30
+
31
+ ```bash
32
+ maximem-synap auth login
33
+ ```
34
+
35
+ Prints a short code and opens your browser. Confirm the code, pick your client,
36
+ approve — and you're logged in. Works over SSH too (just open the printed URL).
37
+
38
+ ```bash
39
+ maximem-synap whoami # which account am I? Also shows user_context_isolation
40
+ maximem-synap auth list # profile, workspace, environment, active marker
41
+ ```
42
+
43
+ `whoami` shows `user_context_isolation` as `b2c` or `b2b` so you can tell them apart without a
44
+ second call. It comes from the server's `/whoami`; if that lacks it, it is read from the one
45
+ instance the key is scoped to, and otherwise it says `unknown` (never a guess).
46
+
47
+ ### Profiles: logins never overwrite another workspace
48
+
49
+ - `auth login --code` names the profile after the workspace (lowercase `a-z0-9-`, at most 30
50
+ characters; `-2`, `-3` on a name clash with another workspace). Logging in again to the same
51
+ workspace and environment updates that profile in place. A different workspace or environment
52
+ always gets its own profile; the old one is left byte for byte as it was.
53
+ - `--profile NAME` always means NAME. If NAME holds a different workspace or environment the
54
+ login is refused with exit 6 (`profile_conflict`) unless you pass `--force`.
55
+ - A one-time-code login (the agent flow) always becomes the active profile, so later commands
56
+ need no `--profile`. If another profile was active, the CLI says so and how to switch back
57
+ (`maximem-synap auth use <name>`); `--output json` carries `previous_active_profile`.
58
+ - Browser login is more conservative: it becomes active only if nothing was active or the active
59
+ profile is the same workspace. Otherwise it prints `Your active profile is still <other>`.
60
+ - Long-running commands (`instances wait`) capture the profile and key once at start, so a login
61
+ that rewrites the config mid-run does not change who they talk to.
62
+
63
+ ## What you can do
64
+
65
+ ```bash
66
+ maximem-synap instances list
67
+ maximem-synap instances create --name "Acme Support" --relationship b2c
68
+ maximem-synap api-keys create --instance <id> --label prod # shown once
69
+ maximem-synap client members list
70
+ maximem-synap --help
71
+ ```
72
+
73
+ Use `--output json` (or its alias `--json`) on any command for scripting, and
74
+ `--profile <name>` to keep multiple accounts side by side. Global flags (`--output`,
75
+ `--json`, `--profile`, `--env`, `--api-base`, `--verbose`) may be placed before or after the
76
+ command. `--json` together with `--output table|csv` is a usage error (exit 2).
77
+
78
+ ## CI / non-interactive
79
+
80
+ No browser? Authenticate with a key instead of `auth login`:
81
+
82
+ ```bash
83
+ export SYNAP_API_KEY=synap_... # from `maximem-synap api-keys create`
84
+ maximem-synap instances list --output json
85
+ ```
86
+
87
+ `SYNAP_API_KEY` overrides any profile and writes nothing to disk. Or persist a key
88
+ with `maximem-synap auth activate --key synap_...`.
89
+
90
+ ## Agent-driven setup (no browser, no prompts)
91
+
92
+ Everything a coding agent needs runs without a TTY or a browser:
93
+
94
+ ```bash
95
+ maximem-synap auth login --code syn_ob_XXXX-XXXX-XXXX # or SYNAP_ONBOARDING_CODE=...
96
+ maximem-synap onboard status -o json # where is setup up to?
97
+ maximem-synap instances template --output-file usecase.md # the use-case template
98
+ maximem-synap instances create --name "Acme" --relationship <b2c|b2b|internal|agent_to_agent> --from-file usecase.md
99
+ # or: ... --from-stdin < usecase.md (--relationship is always required: no default, asked of the human)
100
+ maximem-synap api-keys create -i <id> --write-env # key goes to ./.env, never printed
101
+ maximem-synap api-keys rotate <key-id> --yes --write-env # new key to ./.env, old one revoked, never printed
102
+ maximem-synap instances wait <id> --timeout 1200 # blocks until the memory build is done
103
+ maximem-synap onboard report integrating in_progress # steps: use_case_drafted, use_case_approved,
104
+ # integrating, env_written
105
+ maximem-synap onboard ask "Is this B2C or B2B?" # tell the dashboard you are waiting; --clear to clear
106
+ maximem-synap skill install [--agent claude-code|cursor|codex|auto]
107
+ ```
108
+
109
+ Onboarding codes work once, expire after 10 minutes and are accepted in any letter case; copy a
110
+ fresh prompt from the dashboard if one is rejected. The code is never printed or logged. Without
111
+ `--code` (or `SYNAP_ONBOARDING_CODE`), `auth login` under `--non-interactive` exits 3 instead of
112
+ opening a browser. Onboarding keys last exactly 7 days and cannot be renewed (`auth refresh` answers 403 `onboarding_key_not_refreshable`, exit 3); after expiry a fresh prompt with a new code is needed. `whoami` only warns in the last 24 hours.
113
+
114
+ `--write-env [PATH]` (default `./.env`) writes `SYNAP_API_KEY` and `SYNAP_INSTANCE_ID`, and for a
115
+ non-production environment also `SYNAP_BASE_URL`, `SYNAP_GRPC_HOST`, `SYNAP_GRPC_PORT` and
116
+ `SYNAP_GRPC_USE_TLS`. It creates the file with mode `0600` and updates existing lines in place: a
117
+ variable already there (also as `export NAME=...` or with a quoted value, even if added by hand
118
+ and repeated) is replaced and kept exactly once, never duplicated. It also adds the file to `.gitignore`, and prints only a masked key
119
+ (`synap_…abcd`) and the path. An existing file keeps its mode, CRLF line endings and `export ` prefixes;
120
+ the gitignore check understands patterns and `!` negations. `api-keys rotate` takes the same flags. `--write-env PATH` is shorthand for `--write-env --env-file PATH`.
121
+
122
+ `instances wait` prints progress on stderr and one JSON object on stdout. If the configuration is
123
+ waiting for review by Synap it exits 1 at once instead of waiting for the timeout.
124
+
125
+ If `SYNAP_API_KEY` holds a runtime key (for example you sourced the project `.env`), management
126
+ calls return 401/403 and the CLI says so; run `env -u SYNAP_API_KEY maximem-synap ...`.
127
+
128
+ ### `--non-interactive`
129
+
130
+ Global flag, also on automatically when stdin is not a TTY or `SYNAP_NON_INTERACTIVE=1`
131
+ (`SYNAP_NON_INTERACTIVE=0` forces prompts back on). A command that would ask a question
132
+ fails instead, naming the flag that answers it (for example `--yes`).
133
+
134
+ ### Exit codes and JSON errors
135
+
136
+ | Code | Meaning |
137
+ |---|---|
138
+ | 0 | ok |
139
+ | 1 | generic error (also: `instances wait` build failed) |
140
+ | 2 | usage / invalid argument / confirmation needed |
141
+ | 3 | auth: not logged in, expired or invalid key or code |
142
+ | 4 | not found |
143
+ | 5 | permission / missing scope |
144
+ | 6 | conflict |
145
+ | 7 | timeout (request or `instances wait`) |
146
+ | 8 | server error or network failure |
147
+
148
+ With `--output json`, errors go to stderr as
149
+ `{"error": {"code": "<snake_case>", "message": "...", "exit_code": N, "hint": "..."}}`.
150
+ When the server sent a structured error body (for example the credits needed and available on a 402, code `insufficient_credits`, exit 1), it is passed through as `error.details`.
151
+ In table mode they stay plain text (a `Hint:` line is added when there is one).
152
+
153
+ ## Config
154
+
155
+ Credentials live in `~/.config/synap/config.json` (mode `0600`). One key per
156
+ profile, bound to one client. `maximem-synap auth logout` revokes server-side and
157
+ removes it locally.
@@ -0,0 +1,11 @@
1
+ """`maximem-synap` — the Synap management CLI.
2
+
3
+ A thin Typer client over the Management API plane (`/api/v1/management/*`).
4
+ Login is a gcloud-style browser device-pairing flow; everything else is
5
+ dashboard-parity operations driven by a `synap_` key + scopes.
6
+
7
+ This package is intentionally dependency-light (typer, httpx, rich, stdlib) and
8
+ imports nothing from `synap.cloud` so it can run standalone.
9
+ """
10
+
11
+ __version__ = "0.3.5"