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.
- maximem_synap_cli-0.3.5/PKG-INFO +178 -0
- maximem_synap_cli-0.3.5/maximem_synap_cli.egg-info/PKG-INFO +178 -0
- maximem_synap_cli-0.3.5/maximem_synap_cli.egg-info/SOURCES.txt +32 -0
- maximem_synap_cli-0.3.5/maximem_synap_cli.egg-info/dependency_links.txt +1 -0
- maximem_synap_cli-0.3.5/maximem_synap_cli.egg-info/entry_points.txt +3 -0
- maximem_synap_cli-0.3.5/maximem_synap_cli.egg-info/requires.txt +3 -0
- maximem_synap_cli-0.3.5/maximem_synap_cli.egg-info/top_level.txt +1 -0
- maximem_synap_cli-0.3.5/pyproject.toml +59 -0
- maximem_synap_cli-0.3.5/setup.cfg +4 -0
- maximem_synap_cli-0.3.5/synap/cli/README.md +157 -0
- maximem_synap_cli-0.3.5/synap/cli/__init__.py +11 -0
- maximem_synap_cli-0.3.5/synap/cli/__main__.py +157 -0
- maximem_synap_cli-0.3.5/synap/cli/action_rows.py +36 -0
- maximem_synap_cli-0.3.5/synap/cli/api.py +402 -0
- maximem_synap_cli-0.3.5/synap/cli/app.py +362 -0
- maximem_synap_cli-0.3.5/synap/cli/commands/__init__.py +1 -0
- maximem_synap_cli-0.3.5/synap/cli/commands/api_keys.py +396 -0
- maximem_synap_cli-0.3.5/synap/cli/commands/auth.py +1277 -0
- maximem_synap_cli-0.3.5/synap/cli/commands/billing.py +342 -0
- maximem_synap_cli-0.3.5/synap/cli/commands/client.py +92 -0
- maximem_synap_cli-0.3.5/synap/cli/commands/config_cmd.py +56 -0
- maximem_synap_cli-0.3.5/synap/cli/commands/instances.py +595 -0
- maximem_synap_cli-0.3.5/synap/cli/commands/memories.py +148 -0
- maximem_synap_cli-0.3.5/synap/cli/commands/onboard.py +220 -0
- maximem_synap_cli-0.3.5/synap/cli/commands/privacy.py +677 -0
- maximem_synap_cli-0.3.5/synap/cli/commands/requests.py +181 -0
- maximem_synap_cli-0.3.5/synap/cli/commands/scoping.py +471 -0
- maximem_synap_cli-0.3.5/synap/cli/commands/skill.py +100 -0
- maximem_synap_cli-0.3.5/synap/cli/commands/visibility.py +302 -0
- maximem_synap_cli-0.3.5/synap/cli/config.py +250 -0
- maximem_synap_cli-0.3.5/synap/cli/envfile.py +232 -0
- maximem_synap_cli-0.3.5/synap/cli/interactive.py +94 -0
- maximem_synap_cli-0.3.5/synap/cli/render.py +169 -0
- 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 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
synap
|
|
@@ -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,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"
|