1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
|
---
tags:
- v3
search:
boost: 2
---
The urfave/cli v3 library supports programmable completion for apps utilizing its framework. This means
that the completion is generated dynamically at runtime by invokiong the app itself with a special hidden
flag. The urfave/cli searches for this flag and activates a different flow for command paths than regular flow
The following shells are supported
- bash
- zsh
- fish
- powershell
Enabling auto complete requires 2 things
- Setting the `EnableShellCompletion` field on root `Command` object to `true`.
- Sourcing the completion script for that particular shell.
The completion script for a particular shell can be retrieved by running the "completion" subcommand
on the app after the `EnableShellCompletion` field on root `Command` object has been set to `true`.
Consider the following program
```go
package main
import (
"fmt"
"log"
"os"
"context"
"github.com/urfave/cli/v3"
)
func main() {
cmd := &cli.Command{
Name: "greet",
EnableShellCompletion: true,
Commands: []*cli.Command{
{
Name: "add",
Aliases: []string{"a"},
Usage: "add a task to the list",
Action: func(ctx context.Context, cmd *cli.Command) error {
fmt.Println("added task: ", cmd.Args().First())
return nil
},
},
{
Name: "complete",
Aliases: []string{"c"},
Usage: "complete a task on the list",
Action: func(ctx context.Context, cmd *cli.Command) error {
fmt.Println("completed task: ", cmd.Args().First())
return nil
},
},
{
Name: "template",
Aliases: []string{"t"},
Usage: "options for task templates",
Commands: []*cli.Command{
{
Name: "add",
Usage: "add a new template",
Action: func(ctx context.Context, cmd *cli.Command) error {
fmt.Println("new task template: ", cmd.Args().First())
return nil
},
},
{
Name: "remove",
Usage: "remove an existing template",
Action: func(ctx context.Context, cmd *cli.Command) error {
fmt.Println("removed task template: ", cmd.Args().First())
return nil
},
},
},
},
},
}
if err := cmd.Run(context.Background(), os.Args); err != nil {
log.Fatal(err)
}
}
```
After compiling this app as `greet` we can generate the autocompletion as following
in bash script
```sh-session
$ greet completion bash
```
This file can be saved to /etc/bash_completion.d/greet or $HOME/.bash_completion.d/greet
where it will be automatically picked in new bash shells. For the current shell these
can be sourced either using filename or from generation command directly
```sh-session
$ source ~/.bash_completion.d/greet
```
```sh-session
$ source <(greet completion bash)
```
The procedure for other shells is similar to bash though the specific paths for each of the
shells may vary. Some of the sections below detail the setup need for other shells as
well as examples in those shells.
#### Default auto-completion
```go
package main
import (
"fmt"
"log"
"os"
"context"
"github.com/urfave/cli/v3"
)
func main() {
cmd := &cli.Command{
EnableShellCompletion: true,
Commands: []*cli.Command{
{
Name: "add",
Aliases: []string{"a"},
Usage: "add a task to the list",
Action: func(ctx context.Context, cmd *cli.Command) error {
fmt.Println("added task: ", cmd.Args().First())
return nil
},
},
{
Name: "complete",
Aliases: []string{"c"},
Usage: "complete a task on the list",
Action: func(ctx context.Context, cmd *cli.Command) error {
fmt.Println("completed task: ", cmd.Args().First())
return nil
},
},
{
Name: "template",
Aliases: []string{"t"},
Usage: "options for task templates",
Commands: []*cli.Command{
{
Name: "add",
Usage: "add a new template",
Action: func(ctx context.Context, cmd *cli.Command) error {
fmt.Println("new task template: ", cmd.Args().First())
return nil
},
},
{
Name: "remove",
Usage: "remove an existing template",
Action: func(ctx context.Context, cmd *cli.Command) error {
fmt.Println("removed task template: ", cmd.Args().First())
return nil
},
},
},
},
},
}
if err := cmd.Run(context.Background(), os.Args); err != nil {
log.Fatal(err)
}
}
```
#### ZSH Support
Adding the following lines to
your ZSH configuration file (usually `.zshrc`) will allow the auto-completion to
persist across new shells:
```sh-session
$ PROG=<myprogram>
$ source path/to/autocomplete/zsh_autocomplete
```
#### ZSH default auto-complete example
#### PowerShell Support
Generate the completion script as save it to `<my program>.ps1` . This file can be moved to
anywhere in your file system. The location of script does not matter, only the file name of the
script has to match the your program's binary name.
To activate it, enter:
```powershell
& path/to/autocomplete/<my program>.ps1
```
To persist across new shells, open the PowerShell profile (with `code $profile`
or `notepad $profile`) and add the line:
```powershell
& path/to/autocomplete/<my program>.ps1
```
|
