[READ-ONLY] Mirror of https://github.com/bombshell-dev/tab. shell autocompletions for javascript CLIs
chore: readme-gif (#57)
* update
* change gif
* update readme
* update readme
* update
authored by
AmirHossein Sakhravi
and committed by
GitHub
(Sep 26, 2025, 1:25 PM +0330)
4550eca6
1080e7c5
+42
-20
+42
-20
README.md
+42
-20
README.md
···
1
-
> A video showcasing how pnpm autocompletions work on a test CLI command
2
-
> like `my-cli`
1
+
3
2
4
3
# tab
5
4
6
-
Shell autocompletions are largely missing in the JavaScript CLI ecosystem. Tab provides a simple API for adding autocompletions to any JavaScript CLI tool.
5
+
Shell autocompletions are largely missing in the JavaScript CLI ecosystem. tab provides a simple API for adding autocompletions to any JavaScript CLI tool.
7
6
8
7
Additionally, tab supports autocompletions for `pnpm`, `npm`, `yarn`, and `bun`.
9
8
10
9
As CLI tooling authors, if we can spare our users a second or two by not checking documentation or writing the `-h` flag, we're doing them a huge favor. The unconscious mind loves hitting the [TAB] key and always expects feedback. When nothing happens, it breaks the user's flow - a frustration apparent across the whole JavaScript CLI tooling ecosystem.
11
10
12
-
Tab solves this complexity by providing autocompletions that work consistently across `zsh`, `bash`, `fish`, and `powershell`.
11
+
tab solves this complexity by providing autocompletions that work consistently across `zsh`, `bash`, `fish`, and `powershell`.
13
12
14
13
## Installation
15
14
···
92
91
93
92
## Framework Adapters
94
93
95
-
Tab provides adapters for popular JavaScript CLI frameworks.
94
+
tab provides adapters for popular JavaScript CLI frameworks.
96
95
97
96
### CAC Integration
98
97
···
109
108
.option('--host <host>', 'Specify host');
110
109
111
110
// Initialize tab completions
112
-
const completion = tab(cli);
111
+
const completion = await tab(cli);
113
112
114
113
// Add custom completions for option values
115
-
completion.commands.get('dev')?.options.get('--port')!.handler = async () => [
116
-
{ value: '3000', description: 'Development port' },
117
-
{ value: '8080', description: 'Production port' },
118
-
];
114
+
const devCommand = completion.commands.get('dev');
115
+
const portOption = devCommand?.options.get('port');
116
+
if (portOption) {
117
+
portOption.handler = (complete) => {
118
+
complete('3000', 'Development port');
119
+
complete('8080', 'Production port');
120
+
};
121
+
}
119
122
120
123
cli.parse();
121
124
```
···
143
146
const completion = await tab(main);
144
147
145
148
// Add custom completions
146
-
completion.commands.get('dev')?.options.get('--port')!.handler = async () => [
147
-
{ value: '3000', description: 'Development port' },
148
-
{ value: '8080', description: 'Production port' },
149
-
];
149
+
const devCommand = completion.commands.get('dev');
150
+
const portOption = devCommand?.options.get('port');
151
+
if (portOption) {
152
+
portOption.handler = (complete) => {
153
+
complete('3000', 'Development port');
154
+
complete('8080', 'Production port');
155
+
};
156
+
}
150
157
151
158
const cli = createMain(main);
152
159
cli();
···
175
182
const completion = tab(program);
176
183
177
184
// Add custom completions
178
-
completion.commands.get('serve')?.options.get('--port')!.handler = async () => [
179
-
{ value: '3000', description: 'Default port' },
180
-
{ value: '8080', description: 'Alternative port' },
181
-
];
185
+
const serveCommand = completion.commands.get('serve');
186
+
const portOption = serveCommand?.options.get('port');
187
+
if (portOption) {
188
+
portOption.handler = (complete) => {
189
+
complete('3000', 'Default port');
190
+
complete('8080', 'Alternative port');
191
+
};
192
+
}
182
193
183
194
program.parse();
184
195
```
185
196
186
-
Tab uses a standardized completion protocol that any CLI can implement:
197
+
tab uses a standardized completion protocol that any CLI can implement:
187
198
188
199
```bash
189
200
# Generate shell completion script
···
207
218
208
219
## Contributing
209
220
210
-
We welcome contributions! Tab's architecture makes it easy to add support for new package managers or CLI frameworks.
221
+
We welcome contributions! tab's architecture makes it easy to add support for new package managers or CLI frameworks.
222
+
223
+
## Acknowledgments
224
+
225
+
tab was inspired by the great [Cobra](https://github.com/spf13/cobra/) project, which set the standard for CLI tooling in the Go ecosystem.
226
+
227
+
## Adoption Support
228
+
229
+
We want to make it as easy as possible for the JS ecosystem to enjoy great autocompletions.
230
+
We at [thundraa](https://thundraa.com) would be happy to help any open source CLI utility adopt tab.
231
+
If you maintain a CLI and would like autocompletions set up for your users, just [drop the details in our _Adopting tab_ discussion](https://github.com/bombshell-dev/tab/discussions/61).
232
+
We’ll gladly help and even open a PR to get you started.
assets/preview.gif
assets/preview.gif
This is a binary file and will not be displayed.