formist-cli 0.1.0__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.
- formist_cli-0.1.0/.github/workflows/release.yml +18 -0
- formist_cli-0.1.0/.github/workflows/test.yml +17 -0
- formist_cli-0.1.0/.gitignore +10 -0
- formist_cli-0.1.0/LICENSE +21 -0
- formist_cli-0.1.0/PKG-INFO +176 -0
- formist_cli-0.1.0/README.ar.md +169 -0
- formist_cli-0.1.0/README.fr.md +175 -0
- formist_cli-0.1.0/README.md +159 -0
- formist_cli-0.1.0/README.zh-CN.md +156 -0
- formist_cli-0.1.0/docs/screenshot.png +0 -0
- formist_cli-0.1.0/docs/screenshot.svg +33 -0
- formist_cli-0.1.0/pyproject.toml +42 -0
- formist_cli-0.1.0/scripts/render_screenshot.py +237 -0
- formist_cli-0.1.0/src/formist_cli/__init__.py +1 -0
- formist_cli-0.1.0/src/formist_cli/__main__.py +3 -0
- formist_cli-0.1.0/src/formist_cli/airtable.py +238 -0
- formist_cli-0.1.0/src/formist_cli/alerts.py +207 -0
- formist_cli-0.1.0/src/formist_cli/api.py +1027 -0
- formist_cli-0.1.0/src/formist_cli/chat.py +618 -0
- formist_cli-0.1.0/src/formist_cli/chats.py +517 -0
- formist_cli-0.1.0/src/formist_cli/cli.py +1367 -0
- formist_cli-0.1.0/src/formist_cli/cli_support.py +221 -0
- formist_cli-0.1.0/src/formist_cli/connectors.py +358 -0
- formist_cli-0.1.0/src/formist_cli/context.py +164 -0
- formist_cli-0.1.0/src/formist_cli/diff.py +943 -0
- formist_cli-0.1.0/src/formist_cli/doctor.py +128 -0
- formist_cli-0.1.0/src/formist_cli/export.py +427 -0
- formist_cli-0.1.0/src/formist_cli/files.py +670 -0
- formist_cli-0.1.0/src/formist_cli/importer.py +425 -0
- formist_cli-0.1.0/src/formist_cli/kb.py +185 -0
- formist_cli-0.1.0/src/formist_cli/login.py +615 -0
- formist_cli-0.1.0/src/formist_cli/logs.py +781 -0
- formist_cli-0.1.0/src/formist_cli/meetings.py +200 -0
- formist_cli-0.1.0/src/formist_cli/messages.py +414 -0
- formist_cli-0.1.0/src/formist_cli/participants.py +402 -0
- formist_cli-0.1.0/src/formist_cli/prefs.py +328 -0
- formist_cli-0.1.0/src/formist_cli/privileges.py +375 -0
- formist_cli-0.1.0/src/formist_cli/projects.py +127 -0
- formist_cli-0.1.0/src/formist_cli/resolve.py +443 -0
- formist_cli-0.1.0/src/formist_cli/settings.py +199 -0
- formist_cli-0.1.0/src/formist_cli/skill_library.py +246 -0
- formist_cli-0.1.0/src/formist_cli/skills.py +308 -0
- formist_cli-0.1.0/src/formist_cli/space_plan.py +411 -0
- formist_cli-0.1.0/src/formist_cli/spaces.py +693 -0
- formist_cli-0.1.0/src/formist_cli/targets.py +153 -0
- formist_cli-0.1.0/src/formist_cli/textnorm.py +26 -0
- formist_cli-0.1.0/src/formist_cli/tokens.py +339 -0
- formist_cli-0.1.0/src/formist_cli/update.py +433 -0
- formist_cli-0.1.0/src/formist_cli/uploads.py +928 -0
- formist_cli-0.1.0/src/formist_cli/usage_tokens.py +152 -0
- formist_cli-0.1.0/src/formist_cli/users.py +384 -0
- formist_cli-0.1.0/src/formist_cli/whatsapp.py +451 -0
- formist_cli-0.1.0/tests/test_admin_flag_gate.py +97 -0
- formist_cli-0.1.0/tests/test_airtable.py +307 -0
- formist_cli-0.1.0/tests/test_alerts.py +176 -0
- formist_cli-0.1.0/tests/test_api_and_tokens.py +358 -0
- formist_cli-0.1.0/tests/test_api_uploads_transport.py +252 -0
- formist_cli-0.1.0/tests/test_audit_log_shows_the_newest.py +196 -0
- formist_cli-0.1.0/tests/test_chat.py +319 -0
- formist_cli-0.1.0/tests/test_chat_message.py +240 -0
- formist_cli-0.1.0/tests/test_chats.py +324 -0
- formist_cli-0.1.0/tests/test_cli_registration_is_unique.py +125 -0
- formist_cli-0.1.0/tests/test_connector_ops.py +188 -0
- formist_cli-0.1.0/tests/test_connectors.py +271 -0
- formist_cli-0.1.0/tests/test_context.py +224 -0
- formist_cli-0.1.0/tests/test_diff.py +733 -0
- formist_cli-0.1.0/tests/test_doctor.py +185 -0
- formist_cli-0.1.0/tests/test_export.py +265 -0
- formist_cli-0.1.0/tests/test_files.py +158 -0
- formist_cli-0.1.0/tests/test_files_download.py +209 -0
- formist_cli-0.1.0/tests/test_files_merge.py +69 -0
- formist_cli-0.1.0/tests/test_grants_render.py +114 -0
- formist_cli-0.1.0/tests/test_help_matches_the_write_guard.py +148 -0
- formist_cli-0.1.0/tests/test_importer.py +426 -0
- formist_cli-0.1.0/tests/test_kb.py +215 -0
- formist_cli-0.1.0/tests/test_login.py +713 -0
- formist_cli-0.1.0/tests/test_logs.py +566 -0
- formist_cli-0.1.0/tests/test_meetings.py +201 -0
- formist_cli-0.1.0/tests/test_messages.py +460 -0
- formist_cli-0.1.0/tests/test_participants.py +576 -0
- formist_cli-0.1.0/tests/test_prefs.py +321 -0
- formist_cli-0.1.0/tests/test_privileges.py +74 -0
- formist_cli-0.1.0/tests/test_projects.py +119 -0
- formist_cli-0.1.0/tests/test_proposals.py +98 -0
- formist_cli-0.1.0/tests/test_render_screenshot.py +57 -0
- formist_cli-0.1.0/tests/test_report_provenance.py +126 -0
- formist_cli-0.1.0/tests/test_resolve.py +313 -0
- formist_cli-0.1.0/tests/test_settings.py +102 -0
- formist_cli-0.1.0/tests/test_skill_library_install.py +235 -0
- formist_cli-0.1.0/tests/test_skills.py +317 -0
- formist_cli-0.1.0/tests/test_space_plan.py +376 -0
- formist_cli-0.1.0/tests/test_spaces.py +613 -0
- formist_cli-0.1.0/tests/test_stream_transport.py +252 -0
- formist_cli-0.1.0/tests/test_targets.py +148 -0
- formist_cli-0.1.0/tests/test_update.py +417 -0
- formist_cli-0.1.0/tests/test_upload_dir.py +249 -0
- formist_cli-0.1.0/tests/test_uploads.py +646 -0
- formist_cli-0.1.0/tests/test_usage_tokens.py +194 -0
- formist_cli-0.1.0/tests/test_users.py +163 -0
- formist_cli-0.1.0/tests/test_users_writes.py +399 -0
- formist_cli-0.1.0/tests/test_whatsapp.py +484 -0
- formist_cli-0.1.0/uv.lock +174 -0
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
name: release
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
tags: ["v*"]
|
|
6
|
+
|
|
7
|
+
jobs:
|
|
8
|
+
pypi:
|
|
9
|
+
runs-on: ubuntu-latest
|
|
10
|
+
environment: pypi
|
|
11
|
+
permissions:
|
|
12
|
+
id-token: write
|
|
13
|
+
steps:
|
|
14
|
+
- uses: actions/checkout@v4
|
|
15
|
+
- uses: astral-sh/setup-uv@v6
|
|
16
|
+
- run: uv run --python 3.12 pytest -q
|
|
17
|
+
- run: uv build
|
|
18
|
+
- run: uv publish --trusted-publishing always
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
name: test
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
test:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
strategy:
|
|
12
|
+
matrix:
|
|
13
|
+
python: ["3.10", "3.12", "3.14"]
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@v4
|
|
16
|
+
- uses: astral-sh/setup-uv@v6
|
|
17
|
+
- run: uv run --python ${{ matrix.python }} pytest -q
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 WeCarbon
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: formist-cli
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Command-line client for Formist and Evane deployments
|
|
5
|
+
Project-URL: Homepage, https://formist.ai
|
|
6
|
+
Project-URL: Repository, https://github.com/WeCarbon/formist-cli
|
|
7
|
+
Author: WeCarbon
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: cli,formist
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Operating System :: OS Independent
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
15
|
+
Requires-Python: >=3.10
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
|
|
18
|
+
**English** · [简体中文](README.zh-CN.md) · [Français](README.fr.md) · [العربية](README.ar.md)
|
|
19
|
+
|
|
20
|
+
# formist-cli
|
|
21
|
+
|
|
22
|
+
**`fm` is a terminal client for [Formist](https://formist.ai) and [Evane](https://evane.ai)
|
|
23
|
+
deployments, over the exact same API and login the web app uses.**
|
|
24
|
+
|
|
25
|
+

|
|
26
|
+
|
|
27
|
+
<sub>Mock data, rendered by the real `fm` code with `python3 scripts/render_screenshot.py`.</sub>
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## The problem
|
|
32
|
+
|
|
33
|
+
Keeping a Formist or Evane deployment running means asking it small, urgent questions all day:
|
|
34
|
+
is this region healthy, is a connector stuck, did yesterday's migration apply everywhere, which
|
|
35
|
+
of many spaces is this customer's. Each one normally means opening the web app and clicking
|
|
36
|
+
through an admin page, or writing a one-off script against the API and hand-rolling the login.
|
|
37
|
+
Neither is scriptable, and both are slow exactly when speed matters.
|
|
38
|
+
|
|
39
|
+
## The idea
|
|
40
|
+
|
|
41
|
+
`fm` signs in the same way the web app does, so it can only ever do what your own account is
|
|
42
|
+
allowed to do there, nothing more. Every command prints the deployment, space and credential it
|
|
43
|
+
resolved, before it runs, so what is on screen is the full picture, not a guess. A command that
|
|
44
|
+
changes data always shows what it would do first; committing is a separate, explicit step.
|
|
45
|
+
|
|
46
|
+
- **One client, every deployment.** `--host` switches between Formist, Evane, Evane UAE, Formist
|
|
47
|
+
China, or any custom origin, such as a local dev server, same binary, same commands.
|
|
48
|
+
- **Provenance before action.** Every command announces which deployment and space it resolved,
|
|
49
|
+
and where each came from, a flag, a remembered default, or nothing, so a wrong target is caught
|
|
50
|
+
by reading the screen, not by its effect.
|
|
51
|
+
- **Dry run by default.** A command that changes data prints what it would do and waits for
|
|
52
|
+
`--apply`. `fm update`, which applies a batch of changes at once, re-checks the plan still
|
|
53
|
+
matches before committing, so a stale read can't turn into a wrong write.
|
|
54
|
+
- **A credential per deployment.** `fm login` stores an OAuth credential at `0600`, one file per
|
|
55
|
+
host, so signing in to a staging deployment never touches production. `FORMIST_TOKEN` supplies
|
|
56
|
+
one for CI: used as-is, never written to disk, never refreshed.
|
|
57
|
+
- **No surprise dependencies.** Standard library only, Python 3.10+, installs in a second.
|
|
58
|
+
|
|
59
|
+
## Install
|
|
60
|
+
|
|
61
|
+
```sh
|
|
62
|
+
pipx install formist-cli
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Python 3.10 or newer. No third-party dependencies.
|
|
66
|
+
|
|
67
|
+
## Usage
|
|
68
|
+
|
|
69
|
+
### Sign in
|
|
70
|
+
|
|
71
|
+
```sh
|
|
72
|
+
fm login # opens a browser; the credential is stored at 0600
|
|
73
|
+
fm whoami
|
|
74
|
+
fm logout
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
On a machine without a browser, use `fm login --no-browser` and paste the code the page shows.
|
|
78
|
+
For CI, export `FORMIST_TOKEN` with the `token` field of the file `fm login` writes; it is used
|
|
79
|
+
as-is and never written to disk.
|
|
80
|
+
|
|
81
|
+
Credentials live in `~/.config/formist/` (override with `FORMIST_CONFIG_DIR`), one file per host,
|
|
82
|
+
so signing in to one deployment never replaces another.
|
|
83
|
+
|
|
84
|
+
Platform-administration actions need an extra grant: `fm login --admin` requests it, and the
|
|
85
|
+
server only honours the request if your account already has it. Without that flag, a platform
|
|
86
|
+
admin's own token still runs as an ordinary user.
|
|
87
|
+
|
|
88
|
+
### Choosing a deployment
|
|
89
|
+
|
|
90
|
+
`fm` talks to `https://api.formist.ai` by default. `--host` picks another one:
|
|
91
|
+
|
|
92
|
+
| `--host` | API |
|
|
93
|
+
|--------------|---------------------------------------|
|
|
94
|
+
| `formist` | `https://api.formist.ai` (default) |
|
|
95
|
+
| `evane` | `https://api.evane.ai` |
|
|
96
|
+
| `evane-ae` | `https://ae.api.evane.ai` |
|
|
97
|
+
| `formist-cn` | `https://formist-api.we-carbon.com` |
|
|
98
|
+
|
|
99
|
+
Anything else is taken as an API origin, for example `fm --host 127.0.0.1:8160 spaces` for a
|
|
100
|
+
local server. `--host` works before or after the command: `fm --host evane spaces` and
|
|
101
|
+
`fm spaces --host evane` are the same.
|
|
102
|
+
|
|
103
|
+
### Spaces
|
|
104
|
+
|
|
105
|
+
A space is always addressed by its id, never by its name, since names are not unique:
|
|
106
|
+
|
|
107
|
+
```sh
|
|
108
|
+
fm spaces # your own spaces
|
|
109
|
+
fm use --space <space-id> # remember a default space
|
|
110
|
+
fm kb search "venue contract" --space <space-id>
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
`fm use` can also remember a host, for reads only. A command that writes never inherits a
|
|
114
|
+
remembered host: name it with `--host`, or the default (`formist`) is used.
|
|
115
|
+
|
|
116
|
+
### Writes
|
|
117
|
+
|
|
118
|
+
Most commands that change data run as a dry run first and print what they would do; add
|
|
119
|
+
`--apply` to commit. `fm update`, which applies a batch of changes transactionally, is slightly
|
|
120
|
+
different: the dry run prints a plan token, and `--apply <token>` re-runs the dry run to confirm
|
|
121
|
+
the plan still matches before committing. A handful of actions with no undo, such as `fm spaces
|
|
122
|
+
--admin delete`, have no dry run at all and say so in their own `--help`.
|
|
123
|
+
|
|
124
|
+
### Commands
|
|
125
|
+
|
|
126
|
+
Run `fm --help` for the full list and `fm <command> --help` for each one. Every command works
|
|
127
|
+
with your own account's permissions, the same as the web app, and the server re-checks every
|
|
128
|
+
permission on every call: `fm spaces` lists the spaces you belong to, `fm health` is public and
|
|
129
|
+
needs no login, `fm doctor` rolls health up across every deployment, and the rest, `chats`,
|
|
130
|
+
`chat`, `kb`, `get`, `export`, `import`, `diff`, `upload`, `skill-attach`, `entity-fields`,
|
|
131
|
+
`skill-library-install`, `meeting`, `project`, `connector`, `skills-add`, `skills-update`,
|
|
132
|
+
`proposals`, `audit-log`, `connectors`, `files`, read or write your own space the same way.
|
|
133
|
+
|
|
134
|
+
## FAQ
|
|
135
|
+
|
|
136
|
+
**Do I need platform-admin access to use this?**
|
|
137
|
+
No. Every command works with your own account's permissions by default, the same as the web app
|
|
138
|
+
would for that account: `fm spaces`, for example, lists the spaces you belong to. A few
|
|
139
|
+
commands also accept `--admin`, for a platform administrator account; without it, or without
|
|
140
|
+
the matching grant, they refuse locally before any request is sent, and the server still has
|
|
141
|
+
the final say either way.
|
|
142
|
+
|
|
143
|
+
**Can I point it at a local dev server?**
|
|
144
|
+
Yes: `--host` accepts any API origin, not only the four named deployments, for example
|
|
145
|
+
`fm --host 127.0.0.1:8160 health`.
|
|
146
|
+
|
|
147
|
+
**Can I use it in CI, without a browser?**
|
|
148
|
+
Yes: export `FORMIST_TOKEN` with the `token` field from the file `fm login` writes. It is read
|
|
149
|
+
fresh on every invocation, used as-is, and `fm` never writes it to disk or refreshes it.
|
|
150
|
+
|
|
151
|
+
**What stops a write from landing on the wrong deployment?**
|
|
152
|
+
`fm use` only remembers a host for reads; a write always resolves `--host` from the command
|
|
153
|
+
line, defaulting to `formist` if it is not given. There is no "current environment" for a write
|
|
154
|
+
to silently inherit.
|
|
155
|
+
|
|
156
|
+
**Will `fm` ever do something my account couldn't do in the web app?**
|
|
157
|
+
No. It calls the same API with the same credential, and the server enforces every permission on
|
|
158
|
+
every call; `fm` is a different front end for it, not a different set of rights.
|
|
159
|
+
|
|
160
|
+
## Development
|
|
161
|
+
|
|
162
|
+
```sh
|
|
163
|
+
uv sync
|
|
164
|
+
uv run pytest
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
`docs/screenshot.png` is generated from real `fm` output against a local mock server, never
|
|
168
|
+
handwritten:
|
|
169
|
+
|
|
170
|
+
```sh
|
|
171
|
+
python3 scripts/render_screenshot.py
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
## License
|
|
175
|
+
|
|
176
|
+
[MIT](LICENSE) © 2026 WeCarbon
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
[English](README.md) · [简体中文](README.zh-CN.md) · [Français](README.fr.md) · **العربية**
|
|
2
|
+
|
|
3
|
+
<div dir="rtl">
|
|
4
|
+
|
|
5
|
+
# formist-cli
|
|
6
|
+
|
|
7
|
+
**`fm` عميل طرفي لنشرات [Formist](https://formist.ai) و[Evane](https://evane.ai)، يمر
|
|
8
|
+
بنفس الواجهة البرمجية وطريقة تسجيل الدخول التي يستخدمها تطبيق الويب بالضبط.**
|
|
9
|
+
|
|
10
|
+

|
|
11
|
+
|
|
12
|
+
<sub>بيانات تجريبية، معروضة بكود `fm` الحقيقي عبر `python3 scripts/render_screenshot.py`.</sub>
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## المشكلة
|
|
17
|
+
|
|
18
|
+
تشغيل نشرة Formist أو Evane يوميًا يعني سؤالها أسئلة صغيرة لكن عاجلة طوال الوقت: هل هذه
|
|
19
|
+
المنطقة سليمة، هل توقف أحد الموصلات، هل انتشرت ترحيلة الأمس في كل مكان، ولأي عميل تعود
|
|
20
|
+
هذه المساحة من بين عشرات المساحات. كل سؤال من هذه عادة يعني فتح تطبيق الويب والنقر حتى
|
|
21
|
+
صفحة الإدارة المناسبة، أو كتابة سكربت لمرة واحدة يستدعي الواجهة البرمجية مباشرة مع التعامل
|
|
22
|
+
يدويًا مع تسجيل الدخول. لا هذا ولا ذاك يمكن تحويله إلى سكربت قابل لإعادة الاستخدام، وكلاهما
|
|
23
|
+
بطيء في اللحظة التي تحتاج فيها إلى السرعة.
|
|
24
|
+
|
|
25
|
+
## الفكرة
|
|
26
|
+
|
|
27
|
+
يسجّل `fm` الدخول بنفس طريقة تطبيق الويب، فلا يستطيع فعل أكثر مما يستطيع حسابك نفسه فعله
|
|
28
|
+
هناك. تطبع كل أمر، قبل تنفيذه، النشرة والمساحة وبيانات الاعتماد التي حُلّت، فما يظهر على
|
|
29
|
+
الشاشة هو الصورة الكاملة وليس تخمينًا. أي أمر يغيّر البيانات يعرض دائمًا أولًا ما سيفعله؛
|
|
30
|
+
والتثبيت خطوة منفصلة وصريحة.
|
|
31
|
+
|
|
32
|
+
- **عميل واحد لكل النشرات.** يبدّل `--host` بين Formist وEvane وEvane الإمارات
|
|
33
|
+
وFormist الصين، أو أي عنوان مخصص، مثل خادم تطوير محلي، بنفس البرنامج ونفس الأوامر.
|
|
34
|
+
- **المصدر قبل الفعل.** يعلن كل أمر عن النشرة والمساحة اللتين حلّهما، ومن أين جاءت كل
|
|
35
|
+
قيمة: خيار، أو قيمة افتراضية محفوظة، أو لا شيء. يُكتشف الهدف الخاطئ بقراءة الشاشة، لا
|
|
36
|
+
بعد وقوع أثره.
|
|
37
|
+
- **تشغيل تجريبي افتراضيًا.** يعرض الأمر الذي يغيّر البيانات أولًا ما سيفعله وينتظر
|
|
38
|
+
`--apply`. أمر `fm update`، الذي يطبّق دفعة من التغييرات مرة واحدة، يعيد التحقق من أن
|
|
39
|
+
الخطة ما زالت مطابقة قبل التثبيت، حتى لا تتحول قراءة قديمة إلى كتابة خاطئة.
|
|
40
|
+
- **بيانات اعتماد لكل نشرة.** يخزّن `fm login` بيانات اعتماد OAuth بصلاحيات `0600`، ملف
|
|
41
|
+
لكل نشرة، فتسجيل الدخول إلى نشرة تجريبية لا يمس أبدًا بيانات الإنتاج. يوفّر
|
|
42
|
+
`FORMIST_TOKEN` بيانات اعتماد لبيئات التكامل المستمر: تُستخدم كما هي، ولا تُكتب على
|
|
43
|
+
القرص، ولا تُجدَّد.
|
|
44
|
+
- **لا تبعيات مفاجئة.** المكتبة القياسية فقط، Python بإصدار 3.10 أو أحدث، تثبيت في ثانية
|
|
45
|
+
واحدة.
|
|
46
|
+
|
|
47
|
+
## التثبيت
|
|
48
|
+
|
|
49
|
+
```sh
|
|
50
|
+
pipx install formist-cli
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
يحتاج Python 3.10 أو أحدث. بلا تبعيات خارجية.
|
|
54
|
+
|
|
55
|
+
## الاستخدام
|
|
56
|
+
|
|
57
|
+
### تسجيل الدخول
|
|
58
|
+
|
|
59
|
+
```sh
|
|
60
|
+
fm login # opens a browser; the credential is stored at 0600
|
|
61
|
+
fm whoami
|
|
62
|
+
fm logout
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
على جهاز بلا متصفح، استخدم `fm login --no-browser` والصق الرمز الذي تعرضه الصفحة. أما
|
|
66
|
+
في بيئات التكامل المستمر، فصدّر `FORMIST_TOKEN` بقيمة الحقل `token` من الملف الذي يكتبه
|
|
67
|
+
`fm login`؛ يُستخدم كما هو ولا يُكتب على القرص أبدًا.
|
|
68
|
+
|
|
69
|
+
تعيش بيانات الاعتماد في `~/.config/formist/` (يمكن تغيير المسار بـ
|
|
70
|
+
`FORMIST_CONFIG_DIR`)، ملف واحد لكل نشرة، فتسجيل الدخول إلى إحداها لا يستبدل بيانات
|
|
71
|
+
الأخرى أبدًا.
|
|
72
|
+
|
|
73
|
+
تحتاج إجراءات إدارة المنصة صلاحية إضافية: يطلبها `fm login --admin`، ولا يمنحها الخادم
|
|
74
|
+
إلا إذا كان الحساب يملكها فعلًا. بدون هذا الخيار، حتى رمز مسؤول المنصة نفسه يعمل كمستخدم
|
|
75
|
+
عادي فقط.
|
|
76
|
+
|
|
77
|
+
### اختيار النشرة
|
|
78
|
+
|
|
79
|
+
يتوجّه `fm` افتراضيًا إلى `https://api.formist.ai`. يختار `--host` نشرة أخرى:
|
|
80
|
+
|
|
81
|
+
| `--host` | API |
|
|
82
|
+
|--------------|---------------------------------------|
|
|
83
|
+
| `formist` | `https://api.formist.ai` (الافتراضي) |
|
|
84
|
+
| `evane` | `https://api.evane.ai` |
|
|
85
|
+
| `evane-ae` | `https://ae.api.evane.ai` |
|
|
86
|
+
| `formist-cn` | `https://formist-api.we-carbon.com` |
|
|
87
|
+
|
|
88
|
+
أي قيمة أخرى تُعامَل كعنوان واجهة برمجية، مثل
|
|
89
|
+
`fm --host 127.0.0.1:8160 spaces` للاتصال بخادم محلي. يعمل `--host` قبل الأمر أو
|
|
90
|
+
بعده: `fm --host evane spaces` و`fm spaces --host evane` سواء.
|
|
91
|
+
|
|
92
|
+
### المساحات
|
|
93
|
+
|
|
94
|
+
تُعنوَن المساحة دائمًا بمعرّفها، لا باسمها أبدًا، لأن الأسماء غير فريدة:
|
|
95
|
+
|
|
96
|
+
```sh
|
|
97
|
+
fm spaces # your own spaces
|
|
98
|
+
fm use --space <space-id> # remember a default space
|
|
99
|
+
fm kb search "venue contract" --space <space-id>
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
يمكن لـ `fm use` أيضًا حفظ نشرة، لكن للقراءة فقط. لا يرث أي أمر كتابة أبدًا نشرة محفوظة:
|
|
103
|
+
سمّها بـ `--host`، وإلا استُخدمت القيمة الافتراضية (`formist`).
|
|
104
|
+
|
|
105
|
+
### الكتابة
|
|
106
|
+
|
|
107
|
+
تعمل معظم الأوامر التي تغيّر البيانات كتشغيل تجريبي أولًا وتطبع ما ستفعله؛ أضف `--apply`
|
|
108
|
+
للتثبيت. يختلف `fm update` قليلًا، فهو يطبّق دفعة من التغييرات ضمن معاملة واحدة: يطبع
|
|
109
|
+
التشغيل التجريبي رمز خطة، ويعيد `--apply <الرمز>` تشغيل التجربة للتأكد من أن الخطة ما
|
|
110
|
+
زالت مطابقة قبل التثبيت. بعض الإجراءات التي لا رجعة فيها، مثل
|
|
111
|
+
`fm spaces --admin delete`، لا تشغيل تجريبي لها إطلاقًا، وتوضح ذلك في `--help` الخاصة بها.
|
|
112
|
+
|
|
113
|
+
### الأوامر
|
|
114
|
+
|
|
115
|
+
شغّل `fm --help` للقائمة الكاملة، و`fm <command> --help` لكل أمر على حدة. يعمل كل
|
|
116
|
+
أمر بصلاحيات حسابك نفسه، تمامًا كما في تطبيق الويب، ويعيد الخادم التحقق من كل صلاحية
|
|
117
|
+
في كل استدعاء: يسرد `fm spaces` المساحات التي تنتمي إليها، وأمر `fm health` عام ولا
|
|
118
|
+
يحتاج تسجيل دخول، ويجمع `fm doctor` حالة الصحة عبر كل نشرة؛ وبقية الأوامر، وهي `chats`،
|
|
119
|
+
`chat`، `kb`، `get`، `export`، `import`، `diff`، `upload`،
|
|
120
|
+
`skill-attach`، `entity-fields`، `skill-library-install`، `meeting`،
|
|
121
|
+
`project`، `connector`، `skills-add`، `skills-update`، `proposals`،
|
|
122
|
+
`audit-log`، `connectors`، `files`، تقرأ أو تكتب مساحتك بنفس الطريقة.
|
|
123
|
+
|
|
124
|
+
## الأسئلة الشائعة
|
|
125
|
+
|
|
126
|
+
**هل أحتاج صلاحية إدارة المنصة لاستخدام هذه الأداة؟**
|
|
127
|
+
لا. تعمل كل الأوامر افتراضيًا بصلاحيات حسابك نفسه، تمامًا كما يفعل تطبيق الويب لهذا
|
|
128
|
+
الحساب، فأمر `fm spaces`، مثلًا، يسرد المساحات التي تنتمي إليها. تقبل بعض الأوامر أيضًا
|
|
129
|
+
`--admin`، المخصّص لحساب مسؤول المنصة؛ وبدون هذا الخيار، أو بدون الصلاحية المطابقة
|
|
130
|
+
له، تُرفض هذه الأوامر محليًا قبل إرسال أي طلب، والقرار الأخير يبقى للخادم في كل
|
|
131
|
+
الحالات.
|
|
132
|
+
|
|
133
|
+
**هل يمكن توجيهه إلى خادم تطوير محلي؟**
|
|
134
|
+
نعم: يقبل `--host` أي عنوان واجهة برمجية، وليس فقط النشرات الأربع المسمّاة، مثل
|
|
135
|
+
`fm --host 127.0.0.1:8160 health`.
|
|
136
|
+
|
|
137
|
+
**هل يمكن استخدامه في التكامل المستمر، بلا متصفح؟**
|
|
138
|
+
نعم: صدّر `FORMIST_TOKEN` بقيمة الحقل `token` من الملف الذي يكتبه `fm login`. تُقرأ
|
|
139
|
+
القيمة من جديد في كل استدعاء، وتُستخدم كما هي، ولا يكتبها `fm` على القرص ولا يجدّدها
|
|
140
|
+
أبدًا.
|
|
141
|
+
|
|
142
|
+
**ما الذي يمنع كتابة من الوصول إلى النشرة الخطأ؟**
|
|
143
|
+
لا يحفظ `fm use` نشرة إلا للقراءة؛ أما الكتابة فتحلّ `--host` دائمًا من سطر الأوامر،
|
|
144
|
+
وتستخدم `formist` افتراضيًا إن لم يُمرَّر شيء. لا توجد "بيئة حالية" يمكن لأي كتابة أن
|
|
145
|
+
ترثها بصمت.
|
|
146
|
+
|
|
147
|
+
**هل يمكن لـ `fm` أن يفعل شيئًا لا يستطيع حسابي فعله في تطبيق الويب؟**
|
|
148
|
+
لا. فهو يستدعي الواجهة البرمجية نفسها ببيانات الاعتماد نفسها، ويطبّق الخادم كل صلاحية
|
|
149
|
+
في كل استدعاء؛ `fm` مجرد واجهة دخول أخرى إليها، لا مجموعة صلاحيات مختلفة.
|
|
150
|
+
|
|
151
|
+
## التطوير
|
|
152
|
+
|
|
153
|
+
```sh
|
|
154
|
+
uv sync
|
|
155
|
+
uv run pytest
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
يُولَّد `docs/screenshot.png` من مخرجات `fm` الحقيقية، مقابل خادم اختباري محلي، وليس
|
|
159
|
+
رسمًا يدويًا:
|
|
160
|
+
|
|
161
|
+
```sh
|
|
162
|
+
python3 scripts/render_screenshot.py
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
## الترخيص
|
|
166
|
+
|
|
167
|
+
[MIT](LICENSE) © 2026 WeCarbon
|
|
168
|
+
|
|
169
|
+
</div>
|
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
[English](README.md) · [简体中文](README.zh-CN.md) · **Français** · [العربية](README.ar.md)
|
|
2
|
+
|
|
3
|
+
# formist-cli
|
|
4
|
+
|
|
5
|
+
**`fm` est un client en ligne de commande pour les déploiements [Formist](https://formist.ai)
|
|
6
|
+
et [Evane](https://evane.ai), qui passe exactement par la même API et la même connexion que
|
|
7
|
+
l'application web.**
|
|
8
|
+
|
|
9
|
+

|
|
10
|
+
|
|
11
|
+
<sub>Données fictives, générées par le vrai code de `fm` avec `python3 scripts/render_screenshot.py`.</sub>
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Le problème
|
|
16
|
+
|
|
17
|
+
Faire tourner un déploiement Formist ou Evane au quotidien, c'est lui poser sans arrêt des
|
|
18
|
+
questions urgentes : cette région est-elle en bonne santé, un connecteur est-il bloqué, la
|
|
19
|
+
migration d'hier s'est-elle appliquée partout, à qui appartient tel espace parmi des dizaines.
|
|
20
|
+
Chaque question suppose normalement d'ouvrir l'application web, de trouver la bonne page
|
|
21
|
+
d'administration, ou d'écrire un script ad hoc contre l'API en gérant soi-même la connexion.
|
|
22
|
+
Ni l'un ni l'autre ne se scripte, et les deux sont lents au moment précis où il faut aller vite.
|
|
23
|
+
|
|
24
|
+
## L'idée
|
|
25
|
+
|
|
26
|
+
`fm` se connecte de la même façon que l'application web, donc il ne peut faire que ce que
|
|
27
|
+
votre propre compte peut déjà faire là-bas, rien de plus. Chaque commande affiche le
|
|
28
|
+
déploiement, l'espace et l'identifiant qu'elle a résolus avant de s'exécuter, pour que ce qui
|
|
29
|
+
est à l'écran soit l'information complète, pas une supposition. Une commande qui modifie des
|
|
30
|
+
données montre toujours d'abord ce qu'elle ferait ; valider est une étape à part, explicite.
|
|
31
|
+
|
|
32
|
+
- **Un seul client pour chaque déploiement.** `--host` bascule entre Formist, Evane, Evane EAU,
|
|
33
|
+
Formist Chine, ou n'importe quelle origine personnalisée, comme un serveur de développement
|
|
34
|
+
local, avec le même binaire et les mêmes commandes.
|
|
35
|
+
- **La provenance avant l'action.** Chaque commande annonce le déploiement et l'espace qu'elle
|
|
36
|
+
a résolus, et d'où ils viennent : une option, une valeur par défaut mémorisée, ou rien du
|
|
37
|
+
tout. Une mauvaise cible se repère en lisant l'écran, pas par ses conséquences.
|
|
38
|
+
- **Simulation par défaut.** Une commande qui modifie des données affiche d'abord ce qu'elle
|
|
39
|
+
ferait et attend `--apply`. `fm update`, qui applique un lot de changements en une fois,
|
|
40
|
+
revérifie que le plan correspond toujours avant de valider, pour qu'une lecture périmée ne
|
|
41
|
+
devienne jamais une écriture erronée.
|
|
42
|
+
- **Un identifiant par déploiement.** `fm login` enregistre un identifiant OAuth avec les
|
|
43
|
+
droits `0600`, un fichier par déploiement, de sorte que se connecter à un environnement de
|
|
44
|
+
test ne touche jamais la production. `FORMIST_TOKEN` en fournit un pour la CI : utilisé tel
|
|
45
|
+
quel, jamais écrit sur disque, jamais rafraîchi.
|
|
46
|
+
- **Aucune dépendance surprise.** Uniquement la bibliothèque standard, Python 3.10 ou plus,
|
|
47
|
+
une installation en une seconde.
|
|
48
|
+
|
|
49
|
+
## Installation
|
|
50
|
+
|
|
51
|
+
```sh
|
|
52
|
+
pipx install formist-cli
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Python 3.10 ou plus récent. Aucune dépendance tierce.
|
|
56
|
+
|
|
57
|
+
## Utilisation
|
|
58
|
+
|
|
59
|
+
### Connexion
|
|
60
|
+
|
|
61
|
+
```sh
|
|
62
|
+
fm login # opens a browser; the credential is stored at 0600
|
|
63
|
+
fm whoami
|
|
64
|
+
fm logout
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Sur une machine sans navigateur, utilisez `fm login --no-browser` et collez le code affiché
|
|
68
|
+
par la page. Pour la CI, exportez `FORMIST_TOKEN` avec le champ `token` du fichier que
|
|
69
|
+
`fm login` écrit ; il est utilisé tel quel et jamais écrit sur disque.
|
|
70
|
+
|
|
71
|
+
Les identifiants vivent dans `~/.config/formist/` (remplaçable par `FORMIST_CONFIG_DIR`), un
|
|
72
|
+
fichier par déploiement, donc se connecter à l'un ne remplace jamais l'autre.
|
|
73
|
+
|
|
74
|
+
Les actions d'administration de la plateforme demandent un droit supplémentaire :
|
|
75
|
+
`fm login --admin` le demande, et le serveur ne l'accorde que si votre compte le possède déjà.
|
|
76
|
+
Sans cette option, même le jeton d'un administrateur de la plateforme ne fonctionne que comme
|
|
77
|
+
un utilisateur ordinaire.
|
|
78
|
+
|
|
79
|
+
### Choisir un déploiement
|
|
80
|
+
|
|
81
|
+
`fm` s'adresse par défaut à `https://api.formist.ai`. `--host` en choisit un autre :
|
|
82
|
+
|
|
83
|
+
| `--host` | API |
|
|
84
|
+
|--------------|---------------------------------------|
|
|
85
|
+
| `formist` | `https://api.formist.ai` (défaut) |
|
|
86
|
+
| `evane` | `https://api.evane.ai` |
|
|
87
|
+
| `evane-ae` | `https://ae.api.evane.ai` |
|
|
88
|
+
| `formist-cn` | `https://formist-api.we-carbon.com` |
|
|
89
|
+
|
|
90
|
+
Toute autre valeur est prise comme une origine d'API, par exemple
|
|
91
|
+
`fm --host 127.0.0.1:8160 spaces` pour un serveur local. `--host` fonctionne avant ou après la
|
|
92
|
+
commande : `fm --host evane spaces` et `fm spaces --host evane` reviennent au même.
|
|
93
|
+
|
|
94
|
+
### Espaces
|
|
95
|
+
|
|
96
|
+
Un espace se désigne toujours par son identifiant, jamais par son nom, puisque les noms ne
|
|
97
|
+
sont pas uniques :
|
|
98
|
+
|
|
99
|
+
```sh
|
|
100
|
+
fm spaces # your own spaces
|
|
101
|
+
fm use --space <space-id> # remember a default space
|
|
102
|
+
fm kb search "venue contract" --space <space-id>
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
`fm use` peut aussi mémoriser un déploiement, pour la lecture seulement. Une commande
|
|
106
|
+
d'écriture n'hérite jamais d'un déploiement mémorisé : nommez-le avec `--host`, sinon la
|
|
107
|
+
valeur par défaut (`formist`) est utilisée.
|
|
108
|
+
|
|
109
|
+
### Écritures
|
|
110
|
+
|
|
111
|
+
La plupart des commandes qui modifient des données s'exécutent d'abord en simulation et
|
|
112
|
+
affichent ce qu'elles feraient ; ajoutez `--apply` pour valider. `fm update`, qui applique un
|
|
113
|
+
lot de changements de façon transactionnelle, fonctionne un peu différemment : la simulation
|
|
114
|
+
affiche un jeton de plan, et `--apply <jeton>` relance la simulation pour confirmer que le plan
|
|
115
|
+
correspond toujours avant de valider. Quelques actions irréversibles, comme
|
|
116
|
+
`fm spaces --admin delete`, n'ont aucune simulation et le précisent dans leur propre `--help`.
|
|
117
|
+
|
|
118
|
+
### Commandes
|
|
119
|
+
|
|
120
|
+
Lancez `fm --help` pour la liste complète et `fm <commande> --help` pour chacune. Chaque
|
|
121
|
+
commande fonctionne avec les droits de votre propre compte, comme dans l'application web, et
|
|
122
|
+
le serveur revérifie chaque droit à chaque appel : `fm spaces` liste les espaces dont vous
|
|
123
|
+
êtes membre, `fm health` est public et ne demande aucune connexion, `fm doctor` récapitule
|
|
124
|
+
l'état de santé sur chaque déploiement, et le reste, `chats`, `chat`, `kb`, `get`, `export`,
|
|
125
|
+
`import`, `diff`, `upload`, `skill-attach`, `entity-fields`, `skill-library-install`,
|
|
126
|
+
`meeting`, `project`, `connector`, `skills-add`, `skills-update`, `proposals`, `audit-log`,
|
|
127
|
+
`connectors`, `files`, lit ou écrit votre propre espace de la même façon.
|
|
128
|
+
|
|
129
|
+
## FAQ
|
|
130
|
+
|
|
131
|
+
**Ai-je besoin des droits d'administration de la plateforme pour utiliser cet outil ?**
|
|
132
|
+
Non. Par défaut, chaque commande fonctionne avec les droits de votre propre compte, comme le
|
|
133
|
+
ferait l'application web pour ce compte : `fm spaces`, par exemple, liste les espaces dont
|
|
134
|
+
vous êtes membre. Quelques commandes acceptent aussi `--admin`, réservé à un compte
|
|
135
|
+
administrateur de la plateforme ; sans cette option, ou sans le droit correspondant, elles
|
|
136
|
+
sont refusées localement avant même l'envoi d'une requête, et c'est de toute façon le serveur
|
|
137
|
+
qui tranche en dernier ressort.
|
|
138
|
+
|
|
139
|
+
**Puis-je le pointer vers un serveur de développement local ?**
|
|
140
|
+
Oui : `--host` accepte n'importe quelle origine d'API, pas seulement les quatre déploiements
|
|
141
|
+
nommés, par exemple `fm --host 127.0.0.1:8160 health`.
|
|
142
|
+
|
|
143
|
+
**Puis-je l'utiliser en CI, sans navigateur ?**
|
|
144
|
+
Oui : exportez `FORMIST_TOKEN` avec le champ `token` du fichier que `fm login` écrit. Il est
|
|
145
|
+
relu à chaque appel, utilisé tel quel, et `fm` ne l'écrit jamais sur disque ni ne le rafraîchit.
|
|
146
|
+
|
|
147
|
+
**Qu'est-ce qui empêche une écriture d'atterrir sur le mauvais déploiement ?**
|
|
148
|
+
`fm use` ne mémorise un déploiement que pour la lecture ; une écriture résout toujours
|
|
149
|
+
`--host` depuis la ligne de commande, avec `formist` comme valeur par défaut si rien n'est
|
|
150
|
+
donné. Il n'existe pas d'« environnement courant » qu'une écriture pourrait hériter en
|
|
151
|
+
silence.
|
|
152
|
+
|
|
153
|
+
**`fm` peut-il faire quelque chose que mon compte ne pourrait pas faire dans l'application
|
|
154
|
+
web ?**
|
|
155
|
+
Non. Il appelle la même API avec le même identifiant, et le serveur applique chaque droit à
|
|
156
|
+
chaque appel ; `fm` n'est qu'une autre porte d'entrée vers elle, pas un autre ensemble de
|
|
157
|
+
droits.
|
|
158
|
+
|
|
159
|
+
## Développement
|
|
160
|
+
|
|
161
|
+
```sh
|
|
162
|
+
uv sync
|
|
163
|
+
uv run pytest
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
`docs/screenshot.png` est généré à partir d'une vraie sortie de `fm`, contre un serveur de
|
|
167
|
+
test local, jamais dessiné à la main :
|
|
168
|
+
|
|
169
|
+
```sh
|
|
170
|
+
python3 scripts/render_screenshot.py
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
## Licence
|
|
174
|
+
|
|
175
|
+
[MIT](LICENSE) © 2026 WeCarbon
|