Skip to content

Commit d4eb7b5

Browse files
lolegloleg
committed
Merge branch 'main' of github.com:dribdat/docs
2 parents 219a790 + 6352410 commit d4eb7b5

1 file changed

Lines changed: 242 additions & 0 deletions

File tree

‎docs/cli.md‎

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
# Dribdat CLI Documentation
2+
3+
---
4+
5+
## Overview
6+
7+
This Python script provides a command-line interface (CLI) for managing the Dribdat application, built on Flask and Click. It enables administrators to perform bulk operations on events, users, projects, and challenges.
8+
9+
> **Entry Point**: Run with `python cli.py`
10+
11+
The CLI automatically selects the configuration based on the `DRIBDAT_ENV` environment variable:
12+
13+
| Environment Variable | Configuration Used |
14+
|-----------------------|--------------------|
15+
| `DRIBDAT_ENV=prod` | `ProdConfig` |
16+
| Otherwise | `DevConfig` |
17+
18+
For more details see [Configuration docs](https://dribdat.cc/deploy.html#from-source).
19+
20+
---
21+
22+
## Commands Reference
23+
24+
---
25+
26+
### `ls`
27+
List all visible events.
28+
29+
**Usage**
30+
```
31+
python cli.py ls
32+
```
33+
34+
**Output**
35+
- Total count of non-hidden events
36+
- Tab-separated list: `EVENT_ID EVENT_NAME PROJECT_COUNT`
37+
38+
---
39+
40+
### `socialize`
41+
Reset or refresh user profile data.
42+
43+
**Usage**
44+
```
45+
python cli.py socialize [kind...]
46+
```
47+
48+
**Arguments**
49+
| Argument | Required | Description |
50+
|----------|----------|-------------|
51+
| `kind` | No | (Future) Specify which models to refresh (e.g., `users`). Currently refreshes all users. |
52+
53+
**Behavior**
54+
- Calls `User.socialize()` on all users in the database.
55+
- Output: Number of updated users.
56+
57+
---
58+
59+
### `numerise`
60+
Assign numeric identifiers to projects or challenges for a given event.
61+
62+
**Usage**
63+
```
64+
python cli.py numerise EVENT_ID [--clear] [--primes] [--challenges]
65+
```
66+
67+
**Arguments**
68+
| Argument | Required | Type | Default | Description |
69+
|-------------|----------|-----------|---------|-------------|
70+
| `event` | Yes | `int` | - | ID of the event to process. |
71+
| `--clear` | No | `bool` | `False` | If set, clears identifiers instead of setting them. |
72+
| `--primes` | No | `bool` | `False` | Use prime numbers (2, 3, 5, 7, ...) for identifiers. |
73+
| `--challenges` | No | `bool` | `False` | Apply numbering to challenges only (default: projects only). |
74+
75+
**Behavior**
76+
- Only processes non-hidden projects with `progress >= 0`.
77+
- Projects are ordered by `id` (ascending).
78+
- Identifiers are padded with zeros if needed (e.g., `001`, `012`).
79+
80+
**Example Output**
81+
```
82+
Applying numbers to event: My Hackathon
83+
Enumerated 15 projects.
84+
```
85+
86+
---
87+
88+
### `event_start`
89+
Create a new event.
90+
91+
**Usage**
92+
```
93+
python cli.py event_start NAME [START] [FINISH]
94+
```
95+
96+
**Arguments**
97+
| Argument | Required | Type | Default | Description |
98+
|----------|----------|------------|---------|-------------|
99+
| `name` | Yes | `str` | - | Name of the event. |
100+
| `start` | No | `datetime` | Tomorrow | Start time (ISO format, e.g., `2026-06-01T10:00:00`). |
101+
| `finish` | No | `datetime` | 2 days after `start` | End time (ISO format). |
102+
103+
**Behavior**
104+
- Creates an `Event` with the given name, start, and end times.
105+
- Output: ID of the created event.
106+
107+
---
108+
109+
### `imports`
110+
Import events, projects, and users from a datapackage (URI or file).
111+
112+
**Usage**
113+
```
114+
python cli.py imports URI_OR_PATH [LEVEL]
115+
```
116+
117+
**Arguments**
118+
| Argument | Required | Type | Default | Description |
119+
|----------|----------|--------|---------|-------------|
120+
| `url` | Yes | `str` | - | URI (HTTP/HTTPS) or local file path to the datapackage. |
121+
| `level` | No | `str` | `full` | Import mode: `dry run`, `basic`, or `full`. |
122+
123+
**Import Modes**
124+
| Level | Dry Run | All Data | Description |
125+
|----------|---------|----------|-------------|
126+
| `dry run`| Yes | No | Preview changes without saving. |
127+
| `basic` | No | No | Import with minimal data. |
128+
| `full` | No | Yes | Import all available data. |
129+
130+
**Output**
131+
- List of created event names.
132+
- Errors (if any).
133+
134+
---
135+
---
136+
### `exports`
137+
Export system data (users or events) to CSV (stdout).
138+
139+
**Usage**
140+
```
141+
python cli.py exports kind...
142+
```
143+
144+
**Arguments**
145+
| Argument | Required | Type | Description |
146+
|----------|----------|--------|-------------|
147+
| `kind` | Yes | `str` | One or more of: `people`, `events`. |
148+
149+
**Exports**
150+
151+
**`people` (Users)**
152+
Columns: `id, username, email, updated_at, fullname, my_skills, my_wishes, roles, teams, project_ids`
153+
154+
**`events`**
155+
Columns: `name, starts_at, ends_at`
156+
157+
**Example**
158+
```bash
159+
python cli.py exports people > users.csv
160+
python cli.py exports events > events.csv
161+
```
162+
163+
---
164+
---
165+
### `register`
166+
Import users from a CSV file.
167+
168+
**Usage**
169+
```
170+
python cli.py register FILENAME [TESTONLY]
171+
```
172+
173+
**Arguments**
174+
| Argument | Required | Type | Default | Description |
175+
|-----------|----------|-----------|---------|-------------|
176+
| `filename`| Yes | `str` | - | Path to the CSV file. |
177+
| `testonly`| No | `bool` | `False` | If `True`, does not save changes (dry run). |
178+
179+
**Output**
180+
- Number of users imported and updated.
181+
182+
---
183+
---
184+
### `kick`
185+
Clean up inactive or low-scoring user accounts.
186+
187+
**Usage**
188+
```
189+
python cli.py kick [OPTIONS]
190+
```
191+
192+
**Options**
193+
| Option | Type | Default | Description |
194+
|--------------|-----------|---------|-------------|
195+
| `--lowscore` | `bool` | `False` | Target users with no content (low score). |
196+
| `--inactive` | `bool` | `False` | Target inactive users. |
197+
| `--withsso` | `bool` | `False` | Include users with active SSO. |
198+
| `--delete` | `bool` | `False` | Delete users (default: deactivate only). |
199+
| `--score` | `int` | `0` | Minimum score threshold for `--lowscore`. |
200+
201+
**Behavior**
202+
- Targets non-admin users only.
203+
- If `--inactive` and `--lowscore` are both set, only inactive users with no content are targeted.
204+
- If `--delete` is set, users are permanently deleted; otherwise, they are deactivated (`active=False`).
205+
- Safety: Prints a 5-second countdown (Ctrl+C to abort) before execution.
206+
- Output: CSV list of affected users (`username,fullname,email,webpage_url`).
207+
208+
**Example**
209+
```bash
210+
# Deactivate inactive users
211+
python cli.py kick --inactive
212+
213+
# Delete users with no content and score < 5
214+
python cli.py kick --lowscore --delete --score 5
215+
216+
# Deactivate inactive users, including those with SSO
217+
python cli.py kick --inactive --withsso
218+
```
219+
220+
---
221+
---
222+
---
223+
## Helper Functions
224+
225+
| Function | Description |
226+
|----------|-------------|
227+
| `create_app()` | Initializes the Flask app with the correct config (`DevConfig` or `ProdConfig`). |
228+
| `fetch_datapackage()` | Fetches and processes a datapackage from a URI. |
229+
| `load_file_datapackage()` | Loads and processes a datapackage from a local file. |
230+
| `import_users_csv()` | Imports users from a CSV file. |
231+
232+
---
233+
---
234+
## Notes
235+
236+
1. All commands requiring database access use `create_app().app_context()`.
237+
2. Uses `UTC` (from `dribdat.futures`) for datetime operations.
238+
3. Commands like `imports` and `register` support dry-run modes for safety.
239+
4. The `kick` command with `--delete` is irreversible.
240+
5. Future Work:
241+
- `socialize`: The `kind` parameter is not yet implemented (currently refreshes all users).
242+
- `numerise`: Sort order (alphabetic, ID-based, etc.) is hardcoded to `Project.id`.

0 commit comments

Comments
 (0)