[READ-ONLY] Mirror of https://github.com/bombshell-dev/docs.
bomb.sh/docs
feat: Add Args documentation (#12)
* feat: Add Args documentation
* doc(args): add API reference + remove guides
---------
Co-authored-by: Paul Valladares <85648028+dreyfus92@users.noreply.github.com>
authored by
MacFJA
Paul Valladares
and committed by
GitHub
(May 9, 2025, 11:09 AM -0600)
c6d60fd5
4748f76e
+297
+13
astro.config.mjs
+13
astro.config.mjs
···
89
89
},
90
90
{ label: "Guides", autogenerate: { directory: "clack/guides" } },
91
91
],
92
+
},
93
+
{
94
+
label: "Args",
95
+
id: "args",
96
+
icon: "seti:shell",
97
+
link: "/args/getting-started",
98
+
items: [
99
+
{ label: "Basics", link: "/args/getting-started" },
100
+
{
101
+
label: "API",
102
+
link: "args/api",
103
+
},
104
+
],
92
105
}
93
106
]),
94
107
],
+1
package.json
+1
package.json
+8
pnpm-lock.yaml
+8
pnpm-lock.yaml
···
11
11
'@astrojs/starlight':
12
12
specifier: ^0.32.2
13
13
version: 0.32.4(astro@5.5.4(@types/node@22.13.11)(rollup@4.36.0)(typescript@5.8.2))
14
+
'@bomb.sh/args':
15
+
specifier: ^0.3.1
16
+
version: 0.3.1
14
17
'@clack/core':
15
18
specifier: ^0.4.1
16
19
version: 0.4.1
···
86
89
'@babel/types@7.26.10':
87
90
resolution: {integrity: sha512-emqcG3vHrpxUKTrxcblR36dcrcoRDvKmnL/dCL6ZsHaShW80qxCAcNhzQZrpeM765VzEos+xOi4s+r4IXzTwdQ==}
88
91
engines: {node: '>=6.9.0'}
92
+
93
+
'@bomb.sh/args@0.3.1':
94
+
resolution: {integrity: sha512-CwxKrfgcorUPP6KfYD59aRdBYWBTsfsxT+GmoLVnKo5Tmyoqbpo0UNcjngRMyU+6tiPbd18RuIYxhgAn44wU/Q==}
89
95
90
96
'@clack/core@0.4.1':
91
97
resolution: {integrity: sha512-Pxhij4UXg8KSr7rPek6Zowm+5M22rbd2g1nfojHJkxp5YkFqiZ2+YLEM/XGVIzvGOcM0nqjIFxrpDwWRZYWYjA==}
···
1890
1896
dependencies:
1891
1897
'@babel/helper-string-parser': 7.25.9
1892
1898
'@babel/helper-validator-identifier': 7.25.9
1899
+
1900
+
'@bomb.sh/args@0.3.1': {}
1893
1901
1894
1902
'@clack/core@0.4.1':
1895
1903
dependencies:
+182
src/content/docs/args/api.mdx
+182
src/content/docs/args/api.mdx
···
1
+
---
2
+
title: Args
3
+
description: Learn about the Args package and its capabilities
4
+
---
5
+
import { Aside } from '@astrojs/starlight/components';
6
+
7
+
The `@bomb.sh/args` package is a <1kB library for parsing CLI flags. Inspired by Deno's `std/cli` [`parseArgs`](https://github.com/denoland/std/blob/main/cli/parse_args.ts) module.
8
+
9
+
## Features
10
+
11
+
🤏 very small
12
+
13
+
🍃 very simple
14
+
15
+
🏃 very fast (beats [`node:util`](https://nodejs.org/api/util.html#utilparseargsconfig))
16
+
17
+
🔏 strongly typed
18
+
19
+
## Parsing the arguments
20
+
21
+
```ts twoslash
22
+
import { parse } from "@bomb.sh/args"
23
+
24
+
const args = parse(process.argv, {
25
+
default: { a: 1, b: 2, c: "value" },
26
+
alias: { h: "help" },
27
+
boolean: ["foo", "bar"],
28
+
string: ["baz", "qux"],
29
+
array: ["input"],
30
+
});
31
+
```
32
+
33
+
- The first parameter is the raw CLI parameters list (in most case, it will be `process.argv`)
34
+
- The second parameter is the (optional) configuration to parse raw CLI parameters
35
+
36
+
<Aside type="note">
37
+
In this documentation,
38
+
the term <var>option</var> indicate a string prefixed by one or two hyphen (`-`),<br />
39
+
the term <var>argument</var> indicate a string that is not prefixed by hyphen:
40
+
- `--long`: is an option (long variant), named `long`
41
+
- `-l`: is an option (short variant), named `l`
42
+
- `hello-world`: is an argument, its value is `hello-world`
43
+
44
+
---
45
+
the term <var>flag</var> indicate an option that take two value: `true` or `false`
46
+
</Aside>
47
+
48
+
### Parse options
49
+
50
+
#### `default` option
51
+
52
+
It provides the default value to set if the <var>option</var> is missing
53
+
```ts twoslash
54
+
import { parse } from "@bomb.sh/args"
55
+
56
+
const args = parse(process.argv, {
57
+
default: { a: 1, b: 2, c: "value" },
58
+
});
59
+
```
60
+
the variable `args` will be equals to (assuming CLI parameters are `my-command --a=27`):
61
+
```js
62
+
args = {
63
+
_: [],
64
+
a: 27,
65
+
b: 2,
66
+
c: 'value'
67
+
}
68
+
```
69
+
70
+
#### `alias` option
71
+
72
+
It offers an alternative name for an <var>option</var>.<br />
73
+
The object key is the alternative name, the value the name used in the parsing result
74
+
75
+
```ts twoslash
76
+
import { parse } from "@bomb.sh/args"
77
+
78
+
const args = parse(process.argv, {
79
+
alias: { h: 'help' },
80
+
});
81
+
```
82
+
the variable `args` will be equals to (assuming CLI parameters are `my-command -h`):
83
+
```js
84
+
args = {
85
+
_: [],
86
+
help: true
87
+
}
88
+
```
89
+
90
+
#### `boolean` option
91
+
92
+
Indicate that an <var>option</var> is <var>flag</var>, and so <var>argument</var> after it **is not** its value
93
+
94
+
```ts twoslash
95
+
import { parse } from "@bomb.sh/args"
96
+
97
+
const args = parse(process.argv, {
98
+
boolean: ['get'],
99
+
});
100
+
```
101
+
the variable `args` will be equals to (assuming CLI parameters are `my-command --get http://my-url.com`):
102
+
```js
103
+
args = {
104
+
_: ['http://my-url.com'],
105
+
get: true
106
+
}
107
+
```
108
+
109
+
#### `string` option
110
+
111
+
Indicate that an <var>option</var> have a value, and so the <var>argument</var> after it is its value (or an empty string is none is available)
112
+
113
+
```ts twoslash
114
+
import { parse } from "@bomb.sh/args"
115
+
116
+
const args = parse(process.argv, {
117
+
string: ['get', 'user'],
118
+
});
119
+
```
120
+
the variable `args` will be equals to (assuming CLI parameters are `my-command --user --get http://my-url.com`):
121
+
```js
122
+
args = {
123
+
_: [],
124
+
user: '',
125
+
get: 'http://my-url.com'
126
+
}
127
+
```
128
+
129
+
#### `array` option
130
+
131
+
Indicate that an <var>option</var> have a value and can be repeated several times
132
+
133
+
```ts twoslash
134
+
import { parse } from "@bomb.sh/args"
135
+
136
+
const args = parse(process.argv, {
137
+
array: ['tag'],
138
+
});
139
+
```
140
+
the variable `args` will be equals to (assuming CLI parameters are `my-command --tag app:v1 --tag app:latest`):
141
+
```js
142
+
args = {
143
+
_: [],
144
+
tag: ['app:v1', 'app:latest']
145
+
}
146
+
```
147
+
148
+
### Special <var>option</var>
149
+
150
+
#### Negation variant
151
+
152
+
If a boolean <var>option</var> is prefixed by `--no-` it will parse as a `false` <var>flag</var> (without the `no-` prefix)
153
+
154
+
```ts twoslash
155
+
import { parse } from "@bomb.sh/args"
156
+
157
+
const args = parse(process.argv);
158
+
```
159
+
the variable `args` will be equals to (assuming CLI parameters are `my-command --no-color`):
160
+
```js
161
+
args = {
162
+
_: [],
163
+
color: false
164
+
}
165
+
```
166
+
167
+
<Aside type="note">
168
+
If the <var>option</var> is defined as a `string` this behavior is ignored
169
+
```ts twoslash
170
+
import { parse } from "@bomb.sh/args"
171
+
172
+
const args = parse(process.argv, { string: ['no-name'] });
173
+
```
174
+
the variable `args` will be equals to (assuming CLI parameters are `my-command --no-color --no-name John`):
175
+
```js
176
+
args = {
177
+
_: [],
178
+
'color': false
179
+
'no-name': 'John'
180
+
}
181
+
```
182
+
</Aside>
+93
src/content/docs/args/getting-started.mdx
+93
src/content/docs/args/getting-started.mdx
···
1
+
---
2
+
title: Getting Started
3
+
description: Learn how to get started with Args
4
+
---
5
+
6
+
import { Tabs, TabItem } from '@astrojs/starlight/components';
7
+
8
+
A <1kB library for parsing CLI flags. Inspired by Deno's `std/cli` [`parseArgs`](https://github.com/denoland/std/blob/main/cli/parse_args.ts) module.
9
+
10
+
## Features
11
+
12
+
🤏 very small
13
+
14
+
🍃 very simple
15
+
16
+
🏃 very fast (beats [`node:util`](https://nodejs.org/api/util.html#utilparseargsconfig))
17
+
18
+
🔏 strongly typed
19
+
20
+
## Installation
21
+
22
+
You can install Args using npm, yarn, or pnpm:
23
+
24
+
<Tabs>
25
+
<TabItem label="npm" icon="seti:npm">
26
+
```bash
27
+
npm install @bomb.sh/args
28
+
```
29
+
</TabItem>
30
+
<TabItem label="pnpm" icon="pnpm">
31
+
```bash
32
+
pnpm add @bomb.sh/args
33
+
```
34
+
</TabItem>
35
+
<TabItem label="Yarn" icon="seti:yarn">
36
+
```bash
37
+
yarn add @bomb.sh/args
38
+
```
39
+
</TabItem>
40
+
</Tabs>
41
+
42
+
43
+
## Quick Start
44
+
45
+
Basic usage does not require any configuration.
46
+
47
+
```ts twoslash
48
+
import { parse } from "@bomb.sh/args";
49
+
50
+
// my-cli build --bundle -rf --a value --b=value --c 1
51
+
const argv = process.argv.slice(2);
52
+
const args = parse(argv);
53
+
54
+
console.log(args);
55
+
// { _: ['build'], bundle: true, r: true, f: true, a: "value", b: "value", c: 1 }
56
+
```
57
+
58
+
Parsing can be configured to ensure arguments are coerced to specific types, which enhances type safety.
59
+
60
+
```ts twoslash
61
+
import { parse } from "@bomb.sh/args";
62
+
63
+
const args = parse(process.argv, {
64
+
default: { a: 1, b: 2, c: "value" },
65
+
alias: { h: "help" },
66
+
boolean: ["foo", "bar"],
67
+
string: ["baz", "qux"],
68
+
array: ["input"],
69
+
});
70
+
```
71
+
72
+
## Benchmarks
73
+
74
+
```
75
+
mri x 1,650,986 ops/sec ±0.32% (97 runs sampled)
76
+
@bomb.sh/args x 1,407,191 ops/sec ±0.38% (99 runs sampled)
77
+
minimist x 383,506 ops/sec ±0.28% (99 runs sampled)
78
+
node:util x 320,953 ops/sec ±0.35% (98 runs sampled)
79
+
yargs-parser x 31,874 ops/sec ±1.32% (92 runs sampled)
80
+
```
81
+
82
+
## Acknowledgements
83
+
84
+
This package was previously published as `ultraflag` up until `v0.3.0`, when it was renamed to `@bomb.sh/args`.
85
+
86
+
## Next Steps
87
+
88
+
1. Explore the [API Reference](/docs/args/api) for detailed documentation
89
+
2. Join our [Discord community](https://bomb.sh/chat) for support and discussions
90
+
91
+
## Contributing
92
+
93
+
We welcome contributions! Please check out our [Contributing Guide](/contributing) for details on our code of conduct and the process for submitting pull requests.