formist-cli 0.1.0__py3-none-any.whl
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/__init__.py +1 -0
- formist_cli/__main__.py +3 -0
- formist_cli/airtable.py +238 -0
- formist_cli/alerts.py +207 -0
- formist_cli/api.py +1027 -0
- formist_cli/chat.py +618 -0
- formist_cli/chats.py +517 -0
- formist_cli/cli.py +1367 -0
- formist_cli/cli_support.py +221 -0
- formist_cli/connectors.py +358 -0
- formist_cli/context.py +164 -0
- formist_cli/diff.py +943 -0
- formist_cli/doctor.py +128 -0
- formist_cli/export.py +427 -0
- formist_cli/files.py +670 -0
- formist_cli/importer.py +425 -0
- formist_cli/kb.py +185 -0
- formist_cli/login.py +615 -0
- formist_cli/logs.py +781 -0
- formist_cli/meetings.py +200 -0
- formist_cli/messages.py +414 -0
- formist_cli/participants.py +402 -0
- formist_cli/prefs.py +328 -0
- formist_cli/privileges.py +375 -0
- formist_cli/projects.py +127 -0
- formist_cli/resolve.py +443 -0
- formist_cli/settings.py +199 -0
- formist_cli/skill_library.py +246 -0
- formist_cli/skills.py +308 -0
- formist_cli/space_plan.py +411 -0
- formist_cli/spaces.py +693 -0
- formist_cli/targets.py +153 -0
- formist_cli/textnorm.py +26 -0
- formist_cli/tokens.py +339 -0
- formist_cli/update.py +433 -0
- formist_cli/uploads.py +928 -0
- formist_cli/usage_tokens.py +152 -0
- formist_cli/users.py +384 -0
- formist_cli/whatsapp.py +451 -0
- formist_cli-0.1.0.dist-info/METADATA +176 -0
- formist_cli-0.1.0.dist-info/RECORD +44 -0
- formist_cli-0.1.0.dist-info/WHEEL +4 -0
- formist_cli-0.1.0.dist-info/entry_points.txt +2 -0
- formist_cli-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
"""``fm usage-tokens``: system-wide LLM token spend, over ``GET /admin/usage/tokens``.
|
|
2
|
+
|
|
3
|
+
Read-only; there is nothing to apply here.
|
|
4
|
+
|
|
5
|
+
A zero can mean "measured, and it really is zero" or "unmeasured", and
|
|
6
|
+
those are different facts. Every bucket the server returns carries
|
|
7
|
+
``unmeasured_calls`` / ``unpriced_calls`` and the derived
|
|
8
|
+
``tokens_are_lower_bound`` / ``cost_is_lower_bound`` flags. This
|
|
9
|
+
renderer prints them on every row, not only when they are non-zero,
|
|
10
|
+
since a flag that only sometimes appears is easy to miss when scanning
|
|
11
|
+
a column.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
import argparse
|
|
17
|
+
import json
|
|
18
|
+
|
|
19
|
+
from formist_cli import api, context
|
|
20
|
+
from formist_cli.cli_support import PLATFORM_ADMIN_GATE_NOTE, add_admin_flag
|
|
21
|
+
from formist_cli.cli_support import as_dict as _shared_usage_payload
|
|
22
|
+
from formist_cli.cli_support import build_standalone_parser as _build_standalone_parser
|
|
23
|
+
|
|
24
|
+
GROUP_BY_CHOICES = ("source", "operation", "space", "user", "model", "provider", "day")
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class UsageTokensError(Exception):
|
|
28
|
+
"""A refusal about the usage-tokens surface, written for an operator."""
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def render(payload: dict) -> str:
|
|
32
|
+
lines = [
|
|
33
|
+
f"window {payload.get('since')} .. {payload.get('until')}"
|
|
34
|
+
f" group_by={payload.get('group_by')}",
|
|
35
|
+
f"regions {', '.join(payload.get('regions') or [])}",
|
|
36
|
+
]
|
|
37
|
+
if payload.get("meter_enabled") is False:
|
|
38
|
+
lines.append(
|
|
39
|
+
" TOKEN_METER_ENABLED is OFF on this deployment, every number below "
|
|
40
|
+
"is stale by however long it has been off"
|
|
41
|
+
)
|
|
42
|
+
lines.append("")
|
|
43
|
+
lines.append(_row("TOTAL", payload.get("totals") or {}))
|
|
44
|
+
lines.append("")
|
|
45
|
+
groups = payload.get("groups") or []
|
|
46
|
+
if not groups:
|
|
47
|
+
lines.append("(no rows in this window)")
|
|
48
|
+
for g in groups:
|
|
49
|
+
lines.append(_row(str(g.get("label") or g.get("key") or "(unattributed)"), g))
|
|
50
|
+
if payload.get("truncated"):
|
|
51
|
+
lines.append(
|
|
52
|
+
f"\n{len(groups)} of {payload.get('group_count')} groups shown, MORE "
|
|
53
|
+
"EXIST. Raise --limit for the rest."
|
|
54
|
+
)
|
|
55
|
+
return "\n".join(lines)
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def _row(label: str, bucket: dict) -> str:
|
|
59
|
+
"""Render one bucket. The two lower-bound flags are printed
|
|
60
|
+
unconditionally, since a flag that only shows up when it fires is
|
|
61
|
+
easy to miss when scanning.
|
|
62
|
+
"""
|
|
63
|
+
tokens_flag = "LOWER BOUND" if bucket.get("tokens_are_lower_bound") else "measured"
|
|
64
|
+
cost_flag = "LOWER BOUND" if bucket.get("cost_is_lower_bound") else "priced"
|
|
65
|
+
return (
|
|
66
|
+
f"{label:<28.28} calls={bucket.get('calls', 0):<6} "
|
|
67
|
+
f"tokens={bucket.get('total_tokens', 0):<10} ({tokens_flag}) "
|
|
68
|
+
f"cost=${bucket.get('estimated_cost_usd', 0):<10} ({cost_flag}) "
|
|
69
|
+
# Subsets of tokens above, not additive, same as cached_input_tokens,
|
|
70
|
+
# which this line does not print either (see `--json` for the full
|
|
71
|
+
# per-bucket breakdown). Surfaced here because cache_write is priced
|
|
72
|
+
# at a premium.
|
|
73
|
+
f"cache_write={bucket.get('cache_write_tokens', 0)} "
|
|
74
|
+
f"reasoning={bucket.get('reasoning_tokens', 0)} "
|
|
75
|
+
f"unmeasured={bucket.get('unmeasured_calls', 0)} "
|
|
76
|
+
f"unpriced={bucket.get('unpriced_calls', 0)} "
|
|
77
|
+
f"failed={bucket.get('failed_calls', 0)}"
|
|
78
|
+
)
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
_HELP = "system-wide LLM token spend, aggregated across every region (admin, read-only)"
|
|
82
|
+
|
|
83
|
+
_DESCRIPTION = """Total LLM token spend across the whole deployment, sliceable by
|
|
84
|
+
source, operation, space, user, model, provider or day.
|
|
85
|
+
|
|
86
|
+
fm usage-tokens --host evane
|
|
87
|
+
fm usage-tokens --host evane --group-by space --since 2026-09-01
|
|
88
|
+
fm usage-tokens --host evane --group-by model --space <space-uuid>
|
|
89
|
+
|
|
90
|
+
A zero in this table can mean "measured, and it really is zero" or "the
|
|
91
|
+
backend reported no usage"; those are different facts. Every row is labelled
|
|
92
|
+
`measured`/`LOWER BOUND` (tokens) and `priced`/`LOWER BOUND` (cost) so the two
|
|
93
|
+
are never read as the same thing. `unmeasured`/`unpriced`/`failed` are the
|
|
94
|
+
counts behind those labels.
|
|
95
|
+
"""
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def _add_arguments(parser: argparse.ArgumentParser) -> None:
|
|
99
|
+
parser.add_argument(
|
|
100
|
+
"--host",
|
|
101
|
+
default=argparse.SUPPRESS,
|
|
102
|
+
metavar="HOST",
|
|
103
|
+
help="deployment name or API origin (default: formist, or `fm use` for reads); "
|
|
104
|
+
"a write never inherits it",
|
|
105
|
+
)
|
|
106
|
+
parser.add_argument("--group-by", dest="group_by", choices=GROUP_BY_CHOICES, default="source")
|
|
107
|
+
parser.add_argument("--since", default=None, help="ISO-8601; default: 7 days before --until")
|
|
108
|
+
parser.add_argument("--until", default=None, help="ISO-8601; default: now")
|
|
109
|
+
parser.add_argument("--space", dest="space_id", default=None, help="filter to one space UUID")
|
|
110
|
+
parser.add_argument("--user", dest="user_id", default=None, help="filter to one user UUID")
|
|
111
|
+
parser.add_argument("--source", default=None)
|
|
112
|
+
parser.add_argument("--operation", default=None)
|
|
113
|
+
parser.add_argument("--model", default=None)
|
|
114
|
+
parser.add_argument("--provider", default=None)
|
|
115
|
+
parser.add_argument("--limit", type=int, default=None, help="max groups returned (server caps it)")
|
|
116
|
+
parser.add_argument("--json", action="store_true", help="raw JSON instead of a report")
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def add_parser(subparsers) -> argparse.ArgumentParser:
|
|
120
|
+
parser = subparsers.add_parser(
|
|
121
|
+
"usage-tokens", help=_HELP, description=_DESCRIPTION, epilog=PLATFORM_ADMIN_GATE_NOTE,
|
|
122
|
+
formatter_class=argparse.RawDescriptionHelpFormatter,
|
|
123
|
+
)
|
|
124
|
+
_add_arguments(parser)
|
|
125
|
+
add_admin_flag(parser)
|
|
126
|
+
return parser
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def build_standalone_parser() -> argparse.ArgumentParser:
|
|
130
|
+
return _build_standalone_parser(add_parser)
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def run(args) -> int:
|
|
134
|
+
ctx = context.resolve(args, need_token=True)
|
|
135
|
+
params: dict[str, str] = {"group_by": getattr(args, "group_by", None) or "source"}
|
|
136
|
+
for flag in (
|
|
137
|
+
"since", "until", "space_id", "user_id", "source", "operation", "model", "provider",
|
|
138
|
+
):
|
|
139
|
+
value = getattr(args, flag, None)
|
|
140
|
+
if value is not None:
|
|
141
|
+
params[flag] = str(value)
|
|
142
|
+
if getattr(args, "limit", None) is not None:
|
|
143
|
+
params["limit"] = str(args.limit)
|
|
144
|
+
|
|
145
|
+
payload = api.admin_get(ctx.target, "/admin/usage/tokens", token=ctx.token, params=params)
|
|
146
|
+
payload = _usage_payload(payload)
|
|
147
|
+
print(json.dumps(payload, indent=2, ensure_ascii=False) if args.json else render(payload))
|
|
148
|
+
return 0
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
def _usage_payload(payload: object) -> dict:
|
|
152
|
+
return _shared_usage_payload(payload, what="/admin/usage/tokens", error=UsageTokensError)
|
formist_cli/users.py
ADDED
|
@@ -0,0 +1,384 @@
|
|
|
1
|
+
"""``fm users`` - platform user rows, over routes that already exist.
|
|
2
|
+
|
|
3
|
+
GET /admin/users every user, paginated
|
|
4
|
+
GET /admin/users/{id} one user
|
|
5
|
+
GET /admin/users/{id}/spaces their memberships, with region and role
|
|
6
|
+
|
|
7
|
+
The defect this command can fall into is not the HTTP call: it is a
|
|
8
|
+
report that is true about what it fetched and false about what exists.
|
|
9
|
+
``/admin/users`` is paginated and capped by ``MAX_LIMIT``, so printing 50
|
|
10
|
+
rows without saying there are 312 tells an operator the platform has 50
|
|
11
|
+
users. Every number on screen is real and the conclusion is wrong.
|
|
12
|
+
|
|
13
|
+
:func:`render_list` therefore reports shown and total together, and names
|
|
14
|
+
the flag that widens the view. It also stays quiet when nothing was
|
|
15
|
+
truncated: an alarm that fires when nothing is wrong is an alarm nobody
|
|
16
|
+
reads, and then it is not there for the case that matters.
|
|
17
|
+
|
|
18
|
+
What the surface cannot do is said in ``--help`` because the operator
|
|
19
|
+
meets that and not this file. ``/admin/users`` takes ``limit``/``offset``
|
|
20
|
+
and nothing else: there is no ``q``. An empty page therefore does not
|
|
21
|
+
mean "no such user", and a ``--help`` that stayed silent would invite
|
|
22
|
+
exactly that reading.
|
|
23
|
+
|
|
24
|
+
Reports what can be known, and labels how far each field can be trusted.
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
from __future__ import annotations
|
|
28
|
+
|
|
29
|
+
import argparse
|
|
30
|
+
import json
|
|
31
|
+
|
|
32
|
+
from formist_cli import api, context
|
|
33
|
+
from formist_cli.cli_support import (
|
|
34
|
+
PLATFORM_ADMIN_GATE_NOTE,
|
|
35
|
+
add_admin_flag,
|
|
36
|
+
pagination_footer,
|
|
37
|
+
render_grant_rows,
|
|
38
|
+
)
|
|
39
|
+
from formist_cli.cli_support import as_dict as _shared_as_dict
|
|
40
|
+
from formist_cli.cli_support import build_standalone_parser as _build_standalone_parser
|
|
41
|
+
from formist_cli.targets import require_space_id
|
|
42
|
+
|
|
43
|
+
SUBJECTS = (
|
|
44
|
+
"list", "show", "spaces", "grants",
|
|
45
|
+
"create", "set", "add-space", "remove-space",
|
|
46
|
+
)
|
|
47
|
+
DEFAULT_SUBJECT = "list"
|
|
48
|
+
|
|
49
|
+
#: Write subjects, resolved with ``for_write=True`` (never inherits ``--env``
|
|
50
|
+
#: from ``fm use``), same reasoning as every other mutating command in this CLI.
|
|
51
|
+
_WRITE_SUBJECTS = frozenset({"create", "set", "add-space", "remove-space"})
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
class UsersError(Exception):
|
|
55
|
+
"""A refusal about the user surface, written for an operator."""
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def canonical_subject(subject: str | None) -> str:
|
|
59
|
+
if subject is None:
|
|
60
|
+
return DEFAULT_SUBJECT
|
|
61
|
+
value = subject.strip().lower()
|
|
62
|
+
if value not in SUBJECTS:
|
|
63
|
+
raise UsersError(
|
|
64
|
+
f"unknown subcommand {subject!r}. Valid: {', '.join(SUBJECTS)}.\n"
|
|
65
|
+
" list every user on the platform (paginated)\n"
|
|
66
|
+
" show one user by id\n"
|
|
67
|
+
" spaces a user's space memberships, with region and role\n"
|
|
68
|
+
" grants every credential this deployment holds for them (admin)\n"
|
|
69
|
+
" create provision a user by email (no password, magic-link/OAuth)\n"
|
|
70
|
+
" set update name and/or --platform-admin on/off\n"
|
|
71
|
+
" add-space assign (or re-role) a user in a space\n"
|
|
72
|
+
" remove-space unassign a user from a space"
|
|
73
|
+
)
|
|
74
|
+
return value
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
# ===========================================================================
|
|
78
|
+
# Rendering
|
|
79
|
+
# ===========================================================================
|
|
80
|
+
def render_list(payload: dict) -> str:
|
|
81
|
+
"""A scannable table that never overstates how much of the platform it saw."""
|
|
82
|
+
items = payload.get("items") or []
|
|
83
|
+
total = payload.get("total")
|
|
84
|
+
offset = int(payload.get("offset") or 0)
|
|
85
|
+
|
|
86
|
+
lines = [
|
|
87
|
+
f"{'email':<38} {'name':<22} {'admin':<6} {'waiting':<8} id",
|
|
88
|
+
f"{'-' * 38} {'-' * 22} {'-' * 6} {'-' * 8} {'-' * 8}",
|
|
89
|
+
]
|
|
90
|
+
for row in items:
|
|
91
|
+
lines.append(
|
|
92
|
+
f"{str(row.get('email') or '-'):<38.38} "
|
|
93
|
+
f"{str(row.get('name') or '-'):<22.22} "
|
|
94
|
+
f"{('yes' if row.get('is_platform_admin') else ''):<6} "
|
|
95
|
+
f"{('yes' if row.get('waiting') else ''):<8} "
|
|
96
|
+
f"{_short(row.get('id'))}"
|
|
97
|
+
)
|
|
98
|
+
|
|
99
|
+
lines.append("\n" + pagination_footer(shown=len(items), total=total, offset=offset))
|
|
100
|
+
return "\n".join(lines)
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def render_user(payload: dict) -> str:
|
|
104
|
+
return json.dumps(payload, indent=2, ensure_ascii=False, sort_keys=True)
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def render_spaces(payload: dict) -> str:
|
|
108
|
+
"""A user's memberships. Says so when there are none.
|
|
109
|
+
|
|
110
|
+
Blank output is indistinguishable from a command that failed quietly, which is
|
|
111
|
+
the single most common way a read tool misleads.
|
|
112
|
+
"""
|
|
113
|
+
items = payload.get("items") or []
|
|
114
|
+
if not items:
|
|
115
|
+
return "(this user is a member of no spaces)"
|
|
116
|
+
lines = [
|
|
117
|
+
f"{'space':<38} {'region':<8} {'role':<10} id",
|
|
118
|
+
f"{'-' * 38} {'-' * 8} {'-' * 10} {'-' * 8}",
|
|
119
|
+
]
|
|
120
|
+
for row in items:
|
|
121
|
+
lines.append(
|
|
122
|
+
f"{str(row.get('name') or '-'):<38.38} "
|
|
123
|
+
f"{str(row.get('region') or '-'):<8} "
|
|
124
|
+
f"{str(row.get('role') or '-'):<10} "
|
|
125
|
+
f"{_short(row.get('space_id'))}"
|
|
126
|
+
)
|
|
127
|
+
return "\n".join(lines)
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def render_grants(payload: dict) -> str:
|
|
131
|
+
"""Every credential held for one user, plus WHERE we looked.
|
|
132
|
+
|
|
133
|
+
``regions_scanned`` is printed rather than dropped: personal connectors are
|
|
134
|
+
region-local, so "this user has no Google connector" and "we only searched one
|
|
135
|
+
database" would otherwise be the same empty table.
|
|
136
|
+
"""
|
|
137
|
+
items = payload.get("items") or []
|
|
138
|
+
regions = payload.get("regions_scanned") or []
|
|
139
|
+
body = render_grant_rows(items)
|
|
140
|
+
return f"{body}\n\nregions scanned: {', '.join(str(r) for r in regions) or '(none)'}"
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
def render_membership_change(payload: dict, *, removed: bool) -> str:
|
|
144
|
+
"""The result of ``add-space`` / ``remove-space``, an operator-facing line,
|
|
145
|
+
not a raw dict, because the interesting fact (which role, which space) is
|
|
146
|
+
two keys the server already named."""
|
|
147
|
+
if removed:
|
|
148
|
+
return f"removed user={payload.get('user_id')} space={payload.get('space_id')}"
|
|
149
|
+
return (
|
|
150
|
+
f"assigned user={payload.get('user_id')} space={payload.get('space_id')} "
|
|
151
|
+
f"role={payload.get('role')}"
|
|
152
|
+
)
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def _short(value) -> str:
|
|
156
|
+
text = str(value or "-")
|
|
157
|
+
return text[:8] if len(text) > 8 else text
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
# ===========================================================================
|
|
161
|
+
# CLI
|
|
162
|
+
# ===========================================================================
|
|
163
|
+
_HELP = "platform user rows: list, show one, or list a user's spaces (admin)"
|
|
164
|
+
|
|
165
|
+
_DESCRIPTION = """Read platform user rows over the admin API.
|
|
166
|
+
|
|
167
|
+
THESE ROWS LIVE IN THE GLOBAL DATABASE regardless of which region a space
|
|
168
|
+
is in: auth is not per-region. Pointing this at a regional API and seeing
|
|
169
|
+
nothing would mean the admin surface is not served there, never that the
|
|
170
|
+
user is absent. /admin is Global-only and `fm` refuses to send it
|
|
171
|
+
elsewhere before opening a socket.
|
|
172
|
+
|
|
173
|
+
THERE IS NO SERVER-SIDE SEARCH. `/admin/users` accepts limit and offset and
|
|
174
|
+
nothing else: no `q`, no email filter. So an empty page means "not on this
|
|
175
|
+
page", NOT "no such user". Page with --offset, or pipe --json to a filter.
|
|
176
|
+
|
|
177
|
+
Every listing reports how many rows it showed AND how many exist, because a
|
|
178
|
+
page of 50 printed on its own reads as a platform with 50 users.
|
|
179
|
+
|
|
180
|
+
WRITES (``create`` / ``set`` / ``add-space`` / ``remove-space``)
|
|
181
|
+
------------------------------------------------------------------
|
|
182
|
+
These reach the same mutating ``/admin/users*`` routes the admin panel
|
|
183
|
+
uses. Every mutating ``/admin`` route writes a ``platform_audit_log`` row
|
|
184
|
+
on the server regardless of which client called it; that is a server-side
|
|
185
|
+
property, not something this CLI has to arrange.
|
|
186
|
+
|
|
187
|
+
None of the four has a server-side dry run (unlike ``fm space-plan``,
|
|
188
|
+
which was built with one): each takes effect immediately, the same as
|
|
189
|
+
clicking the equivalent button in the admin panel. ``--env`` therefore
|
|
190
|
+
never inherits from ``fm use`` on a write, same rule as everywhere else in
|
|
191
|
+
this CLI: a write must be told, not remembered.
|
|
192
|
+
|
|
193
|
+
``set --platform-admin off`` on your own account is refused by the server
|
|
194
|
+
(``cannot-self-demote``); revoking the platform's last admin is refused too
|
|
195
|
+
(``last-platform-admin``); both errors are printed verbatim, not swallowed.
|
|
196
|
+
"""
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
def _add_arguments(parser: argparse.ArgumentParser) -> None:
|
|
201
|
+
parser.add_argument(
|
|
202
|
+
"subject", nargs="?",
|
|
203
|
+
help=f"one of: {', '.join(SUBJECTS)} (default: {DEFAULT_SUBJECT})",
|
|
204
|
+
)
|
|
205
|
+
parser.add_argument(
|
|
206
|
+
"user_id", nargs="?",
|
|
207
|
+
help="user UUID (for `show` / `spaces` / `grants` / `set` / `add-space` / `remove-space`)",
|
|
208
|
+
)
|
|
209
|
+
parser.add_argument(
|
|
210
|
+
"--host",
|
|
211
|
+
default=argparse.SUPPRESS,
|
|
212
|
+
metavar="HOST",
|
|
213
|
+
help="deployment name or API origin (default: formist, or `fm use` for reads); "
|
|
214
|
+
"a write never inherits it",
|
|
215
|
+
)
|
|
216
|
+
parser.add_argument("--limit", type=int, default=None, help="rows per page (server caps it)")
|
|
217
|
+
parser.add_argument("--offset", type=int, default=None, help="skip this many rows")
|
|
218
|
+
parser.add_argument("--json", action="store_true", help="raw JSON instead of a table")
|
|
219
|
+
parser.add_argument("--email", default=None, help="`create`: the new user's email")
|
|
220
|
+
parser.add_argument("--name", default=None, help="`create`/`set`: display name")
|
|
221
|
+
parser.add_argument(
|
|
222
|
+
"--platform-admin", dest="platform_admin", choices=("on", "off"), default=None,
|
|
223
|
+
help="`set`: grant/revoke User.is_platform_admin, the highest-blast-radius "
|
|
224
|
+
"flag on this whole surface",
|
|
225
|
+
)
|
|
226
|
+
parser.add_argument(
|
|
227
|
+
"--space", default=None,
|
|
228
|
+
help="`add-space`/`remove-space`: the space UUID (never a name)",
|
|
229
|
+
)
|
|
230
|
+
parser.add_argument(
|
|
231
|
+
"--role", default="USER",
|
|
232
|
+
help="`add-space`: OWNER, ADMIN, USER or VIEWER (default: USER)",
|
|
233
|
+
)
|
|
234
|
+
add_admin_flag(parser)
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
def add_parser(subparsers) -> argparse.ArgumentParser:
|
|
238
|
+
parser = subparsers.add_parser(
|
|
239
|
+
"users", help=_HELP, description=_DESCRIPTION, epilog=PLATFORM_ADMIN_GATE_NOTE,
|
|
240
|
+
formatter_class=argparse.RawDescriptionHelpFormatter,
|
|
241
|
+
)
|
|
242
|
+
_add_arguments(parser)
|
|
243
|
+
return parser
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
def build_standalone_parser() -> argparse.ArgumentParser:
|
|
247
|
+
"""The same parser, detached, so ``--help`` can be asserted in a test.
|
|
248
|
+
|
|
249
|
+
See :func:`formist_cli.cli_support.build_standalone_parser` for why the
|
|
250
|
+
body lives there; this stays a one-line, no-argument wrapper so callers
|
|
251
|
+
keep calling ``users.build_standalone_parser()``.
|
|
252
|
+
"""
|
|
253
|
+
return _build_standalone_parser(add_parser)
|
|
254
|
+
|
|
255
|
+
|
|
256
|
+
def run(args) -> int:
|
|
257
|
+
subject = canonical_subject(getattr(args, "subject", None))
|
|
258
|
+
if subject in _WRITE_SUBJECTS:
|
|
259
|
+
return _run_write(subject, args)
|
|
260
|
+
# need_token is redundant for this command and kept on purpose. Every read
|
|
261
|
+
# below goes through api.admin_get, which has its own "no stored session"
|
|
262
|
+
# refusal, so removing this changes nothing observable here.
|
|
263
|
+
#
|
|
264
|
+
# It stays because this is one command in a series, and other commands
|
|
265
|
+
# reach api.get, which does not guard. A resolver that refuses for some
|
|
266
|
+
# commands and not others is the drift this module was extracted to end.
|
|
267
|
+
ctx = context.resolve(args, need_token=True)
|
|
268
|
+
|
|
269
|
+
params: dict[str, str] = {}
|
|
270
|
+
if getattr(args, "limit", None) is not None:
|
|
271
|
+
params["limit"] = str(args.limit)
|
|
272
|
+
if getattr(args, "offset", None) is not None:
|
|
273
|
+
params["offset"] = str(args.offset)
|
|
274
|
+
|
|
275
|
+
if subject == "list":
|
|
276
|
+
payload = api.admin_get(ctx.target, "/admin/users", token=ctx.token, params=params)
|
|
277
|
+
print(json.dumps(payload, indent=2) if args.json else render_list(_as_dict(payload)))
|
|
278
|
+
return 0
|
|
279
|
+
|
|
280
|
+
user_id = getattr(args, "user_id", None)
|
|
281
|
+
if not user_id:
|
|
282
|
+
raise UsersError(
|
|
283
|
+
f"`fm users {subject}` needs a user id.\n"
|
|
284
|
+
"-> `fm users list` prints them (id is the last column)."
|
|
285
|
+
)
|
|
286
|
+
|
|
287
|
+
if subject == "show":
|
|
288
|
+
payload = api.admin_get(ctx.target, f"/admin/users/{user_id}", token=ctx.token)
|
|
289
|
+
print(render_user(_as_dict(payload)))
|
|
290
|
+
return 0
|
|
291
|
+
|
|
292
|
+
if subject == "grants":
|
|
293
|
+
payload = api.admin_get(
|
|
294
|
+
ctx.target, f"/admin/users/{user_id}/grants", token=ctx.token
|
|
295
|
+
)
|
|
296
|
+
if args.json:
|
|
297
|
+
print(json.dumps(payload, indent=2))
|
|
298
|
+
else:
|
|
299
|
+
print(render_grants(_as_dict(payload)))
|
|
300
|
+
return 0
|
|
301
|
+
|
|
302
|
+
payload = api.admin_get(ctx.target, f"/admin/users/{user_id}/spaces", token=ctx.token)
|
|
303
|
+
print(json.dumps(payload, indent=2) if args.json else render_spaces(_as_dict(payload)))
|
|
304
|
+
return 0
|
|
305
|
+
|
|
306
|
+
|
|
307
|
+
def _run_write(subject: str, args) -> int:
|
|
308
|
+
"""The four mutating subjects. Resolved ``for_write=True``, see the module
|
|
309
|
+
docstring: none of these has a server-side dry run, so ``--env`` must be told
|
|
310
|
+
on every call rather than inherited from ``fm use``."""
|
|
311
|
+
ctx = context.resolve(args, for_write=True, need_token=True)
|
|
312
|
+
|
|
313
|
+
if subject == "create":
|
|
314
|
+
email = (getattr(args, "email", None) or "").strip()
|
|
315
|
+
if not email:
|
|
316
|
+
raise UsersError("`fm users create` needs --email <address>")
|
|
317
|
+
body = {"email": email}
|
|
318
|
+
if getattr(args, "name", None):
|
|
319
|
+
body["name"] = args.name
|
|
320
|
+
payload = api.admin_post(ctx.target, "/admin/users", body, token=ctx.token)
|
|
321
|
+
print(json.dumps(payload, indent=2) if args.json else render_user(_as_dict(payload)))
|
|
322
|
+
return 0
|
|
323
|
+
|
|
324
|
+
user_id = getattr(args, "user_id", None)
|
|
325
|
+
if not user_id:
|
|
326
|
+
raise UsersError(
|
|
327
|
+
f"`fm users {subject}` needs a user id.\n"
|
|
328
|
+
"-> `fm users list` prints them (id is the last column)."
|
|
329
|
+
)
|
|
330
|
+
|
|
331
|
+
if subject == "set":
|
|
332
|
+
fields: dict = {}
|
|
333
|
+
if getattr(args, "name", None):
|
|
334
|
+
fields["name"] = args.name
|
|
335
|
+
if getattr(args, "platform_admin", None) is not None:
|
|
336
|
+
fields["is_platform_admin"] = args.platform_admin == "on"
|
|
337
|
+
if not fields:
|
|
338
|
+
raise UsersError(
|
|
339
|
+
"nothing to set. Name at least one of:\n"
|
|
340
|
+
" --name <text>\n"
|
|
341
|
+
" --platform-admin on|off"
|
|
342
|
+
)
|
|
343
|
+
payload = api.admin_patch(
|
|
344
|
+
ctx.target, f"/admin/users/{user_id}", fields, token=ctx.token
|
|
345
|
+
)
|
|
346
|
+
print(json.dumps(payload, indent=2) if args.json else render_user(_as_dict(payload)))
|
|
347
|
+
return 0
|
|
348
|
+
|
|
349
|
+
space = getattr(args, "space", None)
|
|
350
|
+
if not space:
|
|
351
|
+
raise UsersError(
|
|
352
|
+
f"`fm users {subject}` needs --space <uuid>.\n"
|
|
353
|
+
"-> `fm spaces --host evane` prints them."
|
|
354
|
+
)
|
|
355
|
+
space = require_space_id(space)
|
|
356
|
+
|
|
357
|
+
if subject == "add-space":
|
|
358
|
+
body = {"space_id": space, "role": args.role}
|
|
359
|
+
payload = api.admin_post(
|
|
360
|
+
ctx.target, f"/admin/users/{user_id}/spaces", body, token=ctx.token
|
|
361
|
+
)
|
|
362
|
+
payload = _as_dict(payload)
|
|
363
|
+
print(json.dumps(payload, indent=2) if args.json else
|
|
364
|
+
render_membership_change(payload, removed=False))
|
|
365
|
+
return 0
|
|
366
|
+
|
|
367
|
+
# remove-space
|
|
368
|
+
payload = api.admin_delete(
|
|
369
|
+
ctx.target, f"/admin/users/{user_id}/spaces/{space}", token=ctx.token
|
|
370
|
+
)
|
|
371
|
+
payload = _as_dict(payload)
|
|
372
|
+
print(json.dumps(payload, indent=2) if args.json else
|
|
373
|
+
render_membership_change(payload, removed=True))
|
|
374
|
+
return 0
|
|
375
|
+
|
|
376
|
+
|
|
377
|
+
def _as_dict(payload: object) -> dict:
|
|
378
|
+
""":func:`formist_cli.cli_support.as_dict`, bound to this command's error type.
|
|
379
|
+
|
|
380
|
+
The body moved to ``cli_support`` when ``fm space-plan`` needed the identical
|
|
381
|
+
check; this stays as the one-line binding so the call sites here, and callers
|
|
382
|
+
asserting on ``users._as_dict`` directly, are unchanged.
|
|
383
|
+
"""
|
|
384
|
+
return _shared_as_dict(payload, what="/admin/users", error=UsersError)
|