0
# CLI Interface
1

2
Flask CLI integration that provides command-line access to all migration functionality through the `flask db` command group. The CLI interface mirrors all programmatic API functions with additional command-line specific options and help text.
3

4
## Capabilities
5

6
### Command Group
7

8
Main CLI entry point that groups all database migration commands under a single command namespace.
9

10
```python { .api }
11
@click.group()
12
@click.option('-d', '--directory', default=None,
13
              help='Migration script directory (default is "migrations")')
14
@click.option('-x', '--x-arg', multiple=True,
15
              help='Additional arguments consumed by custom env.py scripts')
16
@with_appcontext
17
def db(directory, x_arg):
18
    """Perform database migrations."""
19
```
20

21
### Core Migration Commands
22

23
Essential CLI commands for the primary migration workflow.
24

25
```bash
26
# Initialize migration repository
27
flask db init [OPTIONS]
28

29
# Create new revision file  
30
flask db revision [OPTIONS]
31

32
# Auto-generate migration (alias for revision --autogenerate)
33
flask db migrate [OPTIONS]
34

35
# Upgrade to later version
36
flask db upgrade [OPTIONS] [REVISION]
37

38
# Downgrade to previous version  
39
flask db downgrade [OPTIONS] [REVISION]
40
```
41

42
### Revision Management Commands
43

44
CLI commands for advanced revision control operations.
45

46
```bash
47
# Edit revision file
48
flask db edit [OPTIONS] [REVISION]
49

50
# Merge revisions together
51
flask db merge [OPTIONS] [REVISIONS]...
52

53
# Stamp revision table without running migrations
54
flask db stamp [OPTIONS] [REVISION]
55
```
56

57
### Information Commands
58

59
CLI commands for inspecting migration state and history.
60

61
```bash
62
# Show revision information
63
flask db show [OPTIONS] [REVISION]
64

65
# List changeset scripts in chronological order
66
flask db history [OPTIONS]
67

68
# Show current available heads
69
flask db heads [OPTIONS]
70

71
# Show current branch points
72
flask db branches [OPTIONS]
73

74
# Display current revision for each database
75
flask db current [OPTIONS]
76

77
# Check if there are any new operations to migrate
78
flask db check [OPTIONS]
79

80
# List available templates
81
flask db list-templates
82
```
83

84
## Command Details
85

86
### Initialize Repository
87

88
```bash
89
flask db init [OPTIONS]
90

91
Options:
92
  -d, --directory TEXT    Migration script directory (default is "migrations")
93
  --multidb               Support multiple databases
94
  -t, --template TEXT     Repository template to use (default is "flask")
95
  --package               Write empty __init__.py files to environment and version locations
96
  --help                  Show this message and exit
97
```
98

99
### Create Revision
100

101
```bash
102
flask db revision [OPTIONS]
103

104
Options:
105
  -d, --directory TEXT        Migration script directory (default is "migrations")
106
  -m, --message TEXT         Revision message
107
  --autogenerate             Populate revision script with candidate migration operations
108
  --sql                      Don't emit SQL to database - dump to standard output instead
109
  --head TEXT                Specify head revision or <branchname>@head to base new revision on
110
  --splice                   Allow a non-head revision as the "head" to splice onto
111
  --branch-label TEXT        Specify a branch label to apply to the new revision
112
  --version-path TEXT        Specify specific path from config for version file
113
  --rev-id TEXT             Specify a hardcoded revision id instead of generating one
114
  --help                    Show this message and exit
115
```
116

117
### Auto-generate Migration
118

119
```bash
120
flask db migrate [OPTIONS]
121

122
Options:
123
  -d, --directory TEXT        Migration script directory (default is "migrations")
124
  -m, --message TEXT         Revision message
125
  --sql                      Don't emit SQL to database - dump to standard output instead
126
  --head TEXT                Specify head revision or <branchname>@head to base new revision on
127
  --splice                   Allow a non-head revision as the "head" to splice onto
128
  --branch-label TEXT        Specify a branch label to apply to the new revision
129
  --version-path TEXT        Specify specific path from config for version file
130
  --rev-id TEXT             Specify a hardcoded revision id instead of generating one
131
  -x, --x-arg TEXT          Additional arguments consumed by custom env.py scripts (multiple)
132
  --help                    Show this message and exit
133
```
134

135
### Upgrade Database
136

137
```bash
138
flask db upgrade [OPTIONS] [REVISION]
139

140
Options:
141
  -d, --directory TEXT    Migration script directory (default is "migrations")
142
  --sql                  Don't emit SQL to database - dump to standard output instead
143
  --tag TEXT            Arbitrary "tag" name - can be used by custom env.py scripts
144
  -x, --x-arg TEXT      Additional arguments consumed by custom env.py scripts (multiple)
145
  --help                Show this message and exit
146

147
Arguments:
148
  REVISION              Target revision (default: head)
149
```
150

151
### Downgrade Database
152

153
```bash
154
flask db downgrade [OPTIONS] [REVISION]
155

156
Options:
157
  -d, --directory TEXT    Migration script directory (default is "migrations")
158
  --sql                  Don't emit SQL to database - dump to standard output instead
159
  --tag TEXT            Arbitrary "tag" name - can be used by custom env.py scripts
160
  -x, --x-arg TEXT      Additional arguments consumed by custom env.py scripts (multiple)
161
  --help                Show this message and exit
162

163
Arguments:
164
  REVISION              Target revision (default: -1)
165
```
166

167
## Usage Examples
168

169
### Basic CLI Workflow
170

171
```bash
172
# Set Flask app environment variable
173
export FLASK_APP=myapp
174

175
# Initialize migration repository
176
flask db init
177

178
# Create initial migration
179
flask db migrate -m "Initial migration"
180

181
# Apply migration to database
182
flask db upgrade
183

184
# Create new migration after model changes
185
flask db migrate -m "Add user email field"
186

187
# Apply new migration
188
flask db upgrade
189
```
190

191
### Advanced CLI Operations
192

193
```bash
194
# Initialize with multi-database support
195
flask db init --multidb
196

197
# Create manual revision (no autogenerate)
198
flask db revision -m "Custom changes"
199

200
# Generate SQL without executing
201
flask db upgrade --sql
202

203
# Downgrade two steps
204
flask db downgrade -2
205

206
# Upgrade to specific revision
207
flask db upgrade abc123
208

209
# Show migration history
210
flask db history --verbose
211

212
# Check current status
213
flask db current
214
```
215

216
### Template and Information Commands
217

218
```bash
219
# List available templates
220
flask db list-templates
221

222
# Initialize with custom template
223
flask db init -t flask-multidb
224

225
# Show specific revision details
226
flask db show abc123
227

228
# Show branch information
229
flask db branches --verbose
230

231
# Merge revisions
232
flask db merge abc123 def456 -m "Merge feature branches"
233
```
234

235
### Custom Environment Arguments
236

237
```bash
238
# Pass custom arguments to env.py scripts
239
flask db upgrade -x custom_arg=value
240

241
# Multiple custom arguments
242
flask db migrate -x db=users -x schema=public -m "Multi-db migration"
243
```
244

245
### Global Options
246

247
All commands support global directory and x-arg options:
248

249
```bash
250
# Use custom migration directory for all commands
251
flask db -d custom_migrations init
252
flask db -d custom_migrations migrate -m "Custom location"
253

254
# Pass custom arguments globally
255
flask db -x global_arg=value migrate -m "Global custom arg"
256
```