0
# CLI Commands
1

2
Command-line interface for user management, role administration, permission synchronization, and database operations. These commands are integrated into Airflow's CLI through the FAB auth manager.
3

4
## Capabilities
5

6
### User Management Commands
7

8
Commands for creating, managing, and maintaining user accounts.
9

10
```python { .api }
11
def users_list(output: str | None = None, verbose: bool = False) -> None:
12
    """List all users in the system."""
13

14
def users_create(
15
    username: str,
16
    email: str, 
17
    firstname: str,
18
    lastname: str,
19
    role: str,
20
    password: str | None = None,
21
    use_random_password: bool = False,
22
    verbose: bool = False
23
) -> None:
24
    """Create a new user account."""
25

26
def user_reset_password(
27
    username: str | None = None,
28
    email: str | None = None, 
29
    password: str | None = None,
30
    use_random_password: bool = False,
31
    verbose: bool = False
32
) -> None:
33
    """Reset a user's password."""
34

35
def users_delete(
36
    username: str | None = None,
37
    email: str | None = None,
38
    verbose: bool = False
39
) -> None:
40
    """Delete a user account."""
41

42
def add_role(
43
    username: str | None = None,
44
    email: str | None = None,
45
    role: str,
46
    verbose: bool = False
47
) -> None:
48
    """Add a role to a user."""
49

50
def remove_role(
51
    username: str | None = None,
52
    email: str | None = None, 
53
    role: str,
54
    verbose: bool = False
55
) -> None:
56
    """Remove a role from a user."""
57

58
def users_import(filepath: str, verbose: bool = False) -> None:
59
    """Import users from JSON file."""
60

61
def users_export(filepath: str, verbose: bool = False) -> None:
62
    """Export all users to JSON file."""
63
```
64

65
### Role Management Commands
66

67
Commands for creating and managing user roles and their permissions.
68

69
```python { .api }
70
def roles_list(
71
    permissions: bool = False,
72
    output: str | None = None, 
73
    verbose: bool = False
74
) -> None:
75
    """List all roles in the system."""
76

77
def roles_create(roles: list[str], verbose: bool = False) -> None:
78
    """Create new roles."""
79

80
def roles_delete(roles: list[str], verbose: bool = False) -> None:
81
    """Delete existing roles."""
82

83
def roles_add_perms(
84
    roles: list[str],
85
    resources: list[str],
86
    actions: list[str],
87
    verbose: bool = False
88
) -> None:
89
    """Add permissions to roles."""
90

91
def roles_del_perms(
92
    roles: list[str],
93
    resources: list[str], 
94
    actions: list[str] | None = None,
95
    verbose: bool = False
96
) -> None:
97
    """Delete permissions from roles."""
98

99
def roles_export(
100
    filepath: str,
101
    pretty: bool = False,
102
    verbose: bool = False
103
) -> None:
104
    """Export roles to JSON file."""
105

106
def roles_import(filepath: str, verbose: bool = False) -> None:
107
    """Import roles from JSON file."""
108
```
109

110
### Permission Synchronization
111

112
Command for synchronizing permissions with the current Airflow installation.
113

114
```python { .api }
115
def sync_perm(include_dags: bool = False, verbose: bool = False) -> None:
116
    """Update permissions for existing roles and optionally DAGs."""
117
```
118

119
### Database Commands
120

121
Commands for managing the FAB metadata database schema (available in Airflow 3.0+).
122

123
```python { .api }
124
def migratedb(
125
    revision: str | None = None,
126
    version: str | None = None,
127
    sql_only: bool = False,
128
    from_revision: str | None = None,
129
    from_version: str | None = None,
130
    verbose: bool = False
131
) -> None:
132
    """Migrate the FAB metadata database to the latest version."""
133

134
def downgrade(
135
    to_revision: str | None = None,
136
    to_version: str | None = None,
137
    sql_only: bool = False,
138
    yes: bool = False,
139
    from_revision: str | None = None,
140
    from_version: str | None = None,
141
    verbose: bool = False
142
) -> None:
143
    """Downgrade the schema of the FAB metadata database."""
144

145
def resetdb(
146
    yes: bool = False,
147
    skip_init: bool = False,
148
    verbose: bool = False
149
) -> None:
150
    """Reset and rebuild the FAB metadata database."""
151
```
152

153
### Utility Functions
154

155
Helper functions used by CLI commands for common operations.
156

157
```python { .api }
158
# Located in cli_commands/utils.py
159
def get_user_by_username_or_email(
160
    username: str | None = None,
161
    email: str | None = None
162
) -> User | None:
163
    """Get user by username or email."""
164

165
def validate_role_exists(role_name: str) -> bool:
166
    """Validate that a role exists in the system."""
167
```
168

169
## Usage Examples
170

171
### User Management
172

173
```bash
174
# List all users
175
airflow users list
176

177
# Create a new admin user
178
airflow users create \
179
    --username admin \
180
    --firstname Admin \
181
    --lastname User \
182
    --role Admin \
183
    --email admin@example.com
184

185
# Reset user password
186
airflow users reset-password --username admin
187

188
# Add role to existing user
189
airflow users add-role --username analyst --role Viewer
190

191
# Import users from JSON file
192
airflow users import users.json
193

194
# Export users to JSON file  
195
airflow users export users_backup.json
196
```
197

198
### Role Management
199

200
```bash
201
# List all roles with permissions
202
airflow roles list --permissions
203

204
# Create new roles
205
airflow roles create DataAnalyst DataViewer
206

207
# Add permissions to role
208
airflow roles add-perms DataAnalyst --resource DAG --action can_read can_edit
209

210
# Remove permissions from role
211
airflow roles del-perms DataViewer --resource Variable --action can_delete
212

213
# Export roles to file
214
airflow roles export roles_backup.json --pretty
215

216
# Import roles from file
217
airflow roles import roles_backup.json
218
```
219

220
### Permission Synchronization
221

222
```bash
223
# Sync permissions (standard resources only)
224
airflow sync-perm
225

226
# Sync permissions including DAG-specific permissions
227
airflow sync-perm --include-dags
228
```
229

230
### Database Management (Airflow 3.0+)
231

232
```bash
233
# Migrate FAB database to latest version
234
airflow fab-db migrate
235

236
# Show migration SQL without executing
237
airflow fab-db migrate --show-sql-only
238

239
# Downgrade to specific revision
240
airflow fab-db downgrade --to-revision abc123
241

242
# Reset FAB database (destructive)
243
airflow fab-db reset --yes
244
```
245

246
## User Import/Export Format
247

248
### User JSON Format
249

250
```json
251
[
252
    {
253
        "email": "user1@example.com",
254
        "firstname": "John", 
255
        "lastname": "Doe",
256
        "roles": ["Viewer", "Op"],
257
        "username": "johndoe"
258
    },
259
    {
260
        "email": "user2@example.com",
261
        "firstname": "Jane",
262
        "lastname": "Smith", 
263
        "roles": ["Admin"],
264
        "username": "janesmith"
265
    }
266
]
267
```
268

269
### Role JSON Format
270

271
```json
272
[
273
    {
274
        "name": "DataAnalyst"
275
    },
276
    {
277
        "name": "DataViewer" 
278
    }
279
]
280
```
281

282
## Types
283

284
```python { .api }
285
from typing import TYPE_CHECKING
286
from airflow.cli.cli_config import CLICommand, ActionCommand, GroupCommand
287

288
if TYPE_CHECKING:
289
    from argparse import Namespace
290
    from airflow.providers.fab.auth_manager.models import User, Role
291
```
292

293
## Command Groups
294

295
The CLI commands are organized into the following groups:
296

297
- **users**: User account management (create, delete, list, import, export, etc.)
298
- **roles**: Role and permission management (create, delete, add/remove permissions, etc.)  
299
- **sync-perm**: Permission synchronization (standalone command)
300
- **fab-db**: Database schema management (Airflow 3.0+ only)