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.
Files changed (102) hide show
  1. formist_cli-0.1.0/.github/workflows/release.yml +18 -0
  2. formist_cli-0.1.0/.github/workflows/test.yml +17 -0
  3. formist_cli-0.1.0/.gitignore +10 -0
  4. formist_cli-0.1.0/LICENSE +21 -0
  5. formist_cli-0.1.0/PKG-INFO +176 -0
  6. formist_cli-0.1.0/README.ar.md +169 -0
  7. formist_cli-0.1.0/README.fr.md +175 -0
  8. formist_cli-0.1.0/README.md +159 -0
  9. formist_cli-0.1.0/README.zh-CN.md +156 -0
  10. formist_cli-0.1.0/docs/screenshot.png +0 -0
  11. formist_cli-0.1.0/docs/screenshot.svg +33 -0
  12. formist_cli-0.1.0/pyproject.toml +42 -0
  13. formist_cli-0.1.0/scripts/render_screenshot.py +237 -0
  14. formist_cli-0.1.0/src/formist_cli/__init__.py +1 -0
  15. formist_cli-0.1.0/src/formist_cli/__main__.py +3 -0
  16. formist_cli-0.1.0/src/formist_cli/airtable.py +238 -0
  17. formist_cli-0.1.0/src/formist_cli/alerts.py +207 -0
  18. formist_cli-0.1.0/src/formist_cli/api.py +1027 -0
  19. formist_cli-0.1.0/src/formist_cli/chat.py +618 -0
  20. formist_cli-0.1.0/src/formist_cli/chats.py +517 -0
  21. formist_cli-0.1.0/src/formist_cli/cli.py +1367 -0
  22. formist_cli-0.1.0/src/formist_cli/cli_support.py +221 -0
  23. formist_cli-0.1.0/src/formist_cli/connectors.py +358 -0
  24. formist_cli-0.1.0/src/formist_cli/context.py +164 -0
  25. formist_cli-0.1.0/src/formist_cli/diff.py +943 -0
  26. formist_cli-0.1.0/src/formist_cli/doctor.py +128 -0
  27. formist_cli-0.1.0/src/formist_cli/export.py +427 -0
  28. formist_cli-0.1.0/src/formist_cli/files.py +670 -0
  29. formist_cli-0.1.0/src/formist_cli/importer.py +425 -0
  30. formist_cli-0.1.0/src/formist_cli/kb.py +185 -0
  31. formist_cli-0.1.0/src/formist_cli/login.py +615 -0
  32. formist_cli-0.1.0/src/formist_cli/logs.py +781 -0
  33. formist_cli-0.1.0/src/formist_cli/meetings.py +200 -0
  34. formist_cli-0.1.0/src/formist_cli/messages.py +414 -0
  35. formist_cli-0.1.0/src/formist_cli/participants.py +402 -0
  36. formist_cli-0.1.0/src/formist_cli/prefs.py +328 -0
  37. formist_cli-0.1.0/src/formist_cli/privileges.py +375 -0
  38. formist_cli-0.1.0/src/formist_cli/projects.py +127 -0
  39. formist_cli-0.1.0/src/formist_cli/resolve.py +443 -0
  40. formist_cli-0.1.0/src/formist_cli/settings.py +199 -0
  41. formist_cli-0.1.0/src/formist_cli/skill_library.py +246 -0
  42. formist_cli-0.1.0/src/formist_cli/skills.py +308 -0
  43. formist_cli-0.1.0/src/formist_cli/space_plan.py +411 -0
  44. formist_cli-0.1.0/src/formist_cli/spaces.py +693 -0
  45. formist_cli-0.1.0/src/formist_cli/targets.py +153 -0
  46. formist_cli-0.1.0/src/formist_cli/textnorm.py +26 -0
  47. formist_cli-0.1.0/src/formist_cli/tokens.py +339 -0
  48. formist_cli-0.1.0/src/formist_cli/update.py +433 -0
  49. formist_cli-0.1.0/src/formist_cli/uploads.py +928 -0
  50. formist_cli-0.1.0/src/formist_cli/usage_tokens.py +152 -0
  51. formist_cli-0.1.0/src/formist_cli/users.py +384 -0
  52. formist_cli-0.1.0/src/formist_cli/whatsapp.py +451 -0
  53. formist_cli-0.1.0/tests/test_admin_flag_gate.py +97 -0
  54. formist_cli-0.1.0/tests/test_airtable.py +307 -0
  55. formist_cli-0.1.0/tests/test_alerts.py +176 -0
  56. formist_cli-0.1.0/tests/test_api_and_tokens.py +358 -0
  57. formist_cli-0.1.0/tests/test_api_uploads_transport.py +252 -0
  58. formist_cli-0.1.0/tests/test_audit_log_shows_the_newest.py +196 -0
  59. formist_cli-0.1.0/tests/test_chat.py +319 -0
  60. formist_cli-0.1.0/tests/test_chat_message.py +240 -0
  61. formist_cli-0.1.0/tests/test_chats.py +324 -0
  62. formist_cli-0.1.0/tests/test_cli_registration_is_unique.py +125 -0
  63. formist_cli-0.1.0/tests/test_connector_ops.py +188 -0
  64. formist_cli-0.1.0/tests/test_connectors.py +271 -0
  65. formist_cli-0.1.0/tests/test_context.py +224 -0
  66. formist_cli-0.1.0/tests/test_diff.py +733 -0
  67. formist_cli-0.1.0/tests/test_doctor.py +185 -0
  68. formist_cli-0.1.0/tests/test_export.py +265 -0
  69. formist_cli-0.1.0/tests/test_files.py +158 -0
  70. formist_cli-0.1.0/tests/test_files_download.py +209 -0
  71. formist_cli-0.1.0/tests/test_files_merge.py +69 -0
  72. formist_cli-0.1.0/tests/test_grants_render.py +114 -0
  73. formist_cli-0.1.0/tests/test_help_matches_the_write_guard.py +148 -0
  74. formist_cli-0.1.0/tests/test_importer.py +426 -0
  75. formist_cli-0.1.0/tests/test_kb.py +215 -0
  76. formist_cli-0.1.0/tests/test_login.py +713 -0
  77. formist_cli-0.1.0/tests/test_logs.py +566 -0
  78. formist_cli-0.1.0/tests/test_meetings.py +201 -0
  79. formist_cli-0.1.0/tests/test_messages.py +460 -0
  80. formist_cli-0.1.0/tests/test_participants.py +576 -0
  81. formist_cli-0.1.0/tests/test_prefs.py +321 -0
  82. formist_cli-0.1.0/tests/test_privileges.py +74 -0
  83. formist_cli-0.1.0/tests/test_projects.py +119 -0
  84. formist_cli-0.1.0/tests/test_proposals.py +98 -0
  85. formist_cli-0.1.0/tests/test_render_screenshot.py +57 -0
  86. formist_cli-0.1.0/tests/test_report_provenance.py +126 -0
  87. formist_cli-0.1.0/tests/test_resolve.py +313 -0
  88. formist_cli-0.1.0/tests/test_settings.py +102 -0
  89. formist_cli-0.1.0/tests/test_skill_library_install.py +235 -0
  90. formist_cli-0.1.0/tests/test_skills.py +317 -0
  91. formist_cli-0.1.0/tests/test_space_plan.py +376 -0
  92. formist_cli-0.1.0/tests/test_spaces.py +613 -0
  93. formist_cli-0.1.0/tests/test_stream_transport.py +252 -0
  94. formist_cli-0.1.0/tests/test_targets.py +148 -0
  95. formist_cli-0.1.0/tests/test_update.py +417 -0
  96. formist_cli-0.1.0/tests/test_upload_dir.py +249 -0
  97. formist_cli-0.1.0/tests/test_uploads.py +646 -0
  98. formist_cli-0.1.0/tests/test_usage_tokens.py +194 -0
  99. formist_cli-0.1.0/tests/test_users.py +163 -0
  100. formist_cli-0.1.0/tests/test_users_writes.py +399 -0
  101. formist_cli-0.1.0/tests/test_whatsapp.py +484 -0
  102. 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,10 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ dist/
5
+ build/
6
+ *.egg-info/
7
+ .pytest_cache/
8
+ .ruff_cache/
9
+ CLAUDE.md
10
+ .claude/
@@ -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
+ ![A terminal running fm health, fm spaces and fm kb search against a Formist deployment](docs/screenshot.png)
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
+ ![طرفية تُشغّل fm health وfm spaces وfm kb search على نشرة Formist](docs/screenshot.png)
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
+ ![Un terminal exécutant fm health, fm spaces et fm kb search sur un déploiement Formist](docs/screenshot.png)
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