Home A - Z
Menu

An Otter Wiki

Blame

861469 Ralph Thesen 2026-08-30 20:16:05
Add CLI page documenting the flask user management commands
1 
# Command Line Interface
2
3
An Otter Wiki ships a Flask command line interface for user management (from
4
version **2.18.0**). It is the recovery path when nobody can log in any more or
5
the mail server is broken, so it works without a browser and without a working
6
login. Every command carries its own `--help`, for example `flask user --help`
7
or `flask user create --help`.
8
9
## Running the CLI
10
11
The environment variable `FLASK_APP=otterwiki.server` must be set. Both docker
12
images set it already, so inside a container the commands are just
13
`flask user ...`.
14
15
### In Docker
16
17
Run the CLI in the running container with `docker compose exec`. Replace
18
`otterwiki` below with the name of your service.
19
20
The full image (`redimp/otterwiki:2`) runs the wiki as the `www-data` user even
21
though the container itself starts as root. Run the CLI as `www-data` too, so
22
that database writes and git commits are not left owned by root in `/app-data`:
23
24
```
25
docker compose exec -u www-data otterwiki flask user list
26
```
27
28
> [!NOTE]
29
> If you set `PUID`/`PGID` on the container, run the CLI as that user instead of
30
> `www-data`. The slim image (`redimp/otterwiki:2-slim`) already runs as
31
> `www-data`, so there `-u` is not needed:
32
> `docker compose exec otterwiki flask user list`.
33
34
### From a source install
35
36
Export `OTTERWIKI_SETTINGS` so the app finds its configuration, then use the
37
`flask` from the virtual environment the app runs in:
38
39
```
40
export OTTERWIKI_SETTINGS=/path/to/settings.cfg
41
venv/bin/flask user list
42
```
43
44
## User management
45
46
Users have three independent attributes the CLI can set:
47
48
- **Flags** `email_confirmed` and `approved`.
49
- **Permissions** `read`, `write`, `upload` and `admin`. Granting `admin`
50
implies `approved`, `read`, `write` and `upload`.
51
- A **password**. A user without a password cannot log in.
52
53
`--flags` and `--permissions` take comma-separated lists, for example
54
`--permissions=read,write`.
55
56
### List users
57
58
```
59
flask user list # human-readable table
60
flask user list --json # machine-readable
61
```
62
63
### Create a user
64
65
`flask user create EMAIL NAME` creates an account. The new user has **no
66
password** and cannot log in until one is set with `flask user password`.
67
68
```
69
flask user create user@example.com "Jane Doe" --flags=email_confirmed,approved --permissions=read,write
70
```
71
72
Short options `-f` (flags) and `-p` (permissions) also work.
73
74
### Set or reset a password
75
76
`flask user password EMAIL` takes exactly one of:
77
78
- `-i`, `--interactive` prompt for the new password.
79
- `-g`, `--generate` generate a 12-character password and print it.
80
- `-r`, `--send-password-reset` email a reset link (requires a configured mail
81
server).
82
- `-d`, `--delete` remove the password, blocking login until a reset.
83
84
### Edit a user
85
86
`flask user edit EMAIL` changes an account. Provide at least one of
87
`--new-email`, `--new-name`, `--flags` or `--permissions`.
88
89
> [!WARNING]
90
> `--flags` and `--permissions` **overwrite** the current values rather than
91
> adding to them. To make someone an admin without dropping their other
92
> attributes, pass the full set you want.
93
94
```
95
flask user edit user@example.com --new-name="Jane Roe" --permissions=read,write,upload
96
```
97
98
### Delete a user
99
100
`flask user delete EMAIL` asks for confirmation first; `-y` / `--confirm`
101
skips it.
102
103
## Recovering admin access
104
105
If you are locked out, create a fresh admin account (or re-grant admin to your
106
own) and generate a password for it:
107
108
```
109
docker compose exec -u www-data otterwiki flask user create you@example.com "You" -p admin
110
docker compose exec -u www-data otterwiki flask user password you@example.com --generate
111
```
112
113
The second command prints the new password. Log in with it and change it from
114
your profile. See the [[FAQ|FAQ#i-locked-myself-out]] for the same recipe from
115
the other direction.