index

citty

Nitroとかh3とかいろいろいい感じのライブラリを作ってるUnJSのライブラリの一つ。いい感じにCLIツールを作れる。

準備

npm install citty

公式のサンプルソースを拝借。

1
import { defineCommand, runMain } from "citty";
2

3
const main = defineCommand({
4
    meta: {
5
        name: "hello",
6
        version: "1.0.0",
7
        description: "My Awesome CLI App",
8
    },
9
    args: {
10
        name: {
11
            type: "positional",
12
            description: "Your name",
13
            required: true,
14
        },
15
        friendly: {
16
            type: "boolean",
17
            description: "Use friendly greeting",
18
        },
19
    },
20
    run({ args }) {
21
        console.log(`${args.friendly ? "Hi" : "Greetings"} ${args.name}!`);
22
    },
23
});
24

25
runMain(main);

基本

以下、あえて間違った動かし方をしてみる。

node --experimental-strip-types index.ts

かなり親切に怒ってくれる。オプションなしで実行してみると…

node --experimental-strip-types index.ts Kanon

オプションをつける。

node --experimental-strip-types index.ts Kanon --friendly true

フレンドリーになった。

argsのtypeについて

1
    args: {
2
        name: {
3
            type: "positional",
4
            description: "Your name",
5
            required: true,
6
        },
7
        friendly: {
8
            type: "boolean",
9
            description: "Use friendly greeting",
10
        },
11
    },

ここで試しにtypeにnumberを指定してみると怒られる。

実装をみると以下のようになっている。

1
type ArgType = "boolean" | "string" | "positional" | undefined;

どうやら4つを指定できるらしい。string, booleanはわかるがpositionalとはなにか。これは--helpで見てみるとわかる。まずは以下のように引数を定義して--helpする。

1
    args: {
2
        name: {
3
            type: "positional",
4
            description: "Your name",
5
            required: true,
6
        },
7
        friendly: {
8
            type: "boolean",
9
            description: "Use friendly greeting",
10
        },
11
        repeat: {
12
            type: "string",
13
            description: "Number of times to repeat the greeting",
14
            default: "2",
15
        },
16
    },

helpもめっちゃわかりやすい。

では次に、friendlyをpositionalに変えてみる。

1
args: {
2
    name: {
3
        type: "positional",
4
        description: "Your name",
5
        required: true,
6
    },
7
    friendly: {
8
         type: "boolean",
9
         type: "positional",
10
        description: "Use friendly greeting",
11
    },
12
    repeat: {
13
        type: "string",
14
        description: "Number of times to repeat the greeting",
15
        default: "2",
16
    },
17
},

--friendlyからFRIENDLYに変わったのがわかるだろうか。つまり、「positionalはargsに指定された順番で受け取るよ」ということらしい。試しに以下のように実行してみると…

node --experimental-strip-types index.ts Kanon

FRIENDLYを指定しろと怒られた。

サブコマンド

サブコマンドを実装することもできる。以下のように二つのサブコマンドを実装してみる。

1
import { defineCommand, runMain } from "citty";
2

3
const greet = defineCommand({
4
    meta: {
5
        name: "greet",
6
        description: "Greet someone",
7
    },
8
    args: {
9
        name: {
10
            type: "positional",
11
            description: "Your name",
12
            required: true,
13
        },
14
        friendly: {
15
            type: "boolean",
16
            description: "Use friendly greeting",
17
        },
18
    },
19
    run({ args }) {
20
        console.log(`${args.friendly ? "Hi" : "Greetings"} ${args.name}!`);
21
    },
22
});
23

24
const byebye = defineCommand({
25
    meta: {
26
        name: "byebye",
27
        description: "Goodbye someone",
28
    },
29
    args: {
30
        name: {
31
            type: "positional",
32
            description: "Your name",
33
            required: true,
34
        },
35
    },
36
    run({ args }) {
37
        console.log(`byebye👋 ${args.name}!`);
38
    },
39
});
40

41
const main = defineCommand({
42
    meta: {
43
        name: "hello",
44
        version: "1.0.0",
45
        description: "My Awesome CLI App",
46
    },
47
    subCommands: {
48
        greet,
49
        byebye,
50
    },
51
});
52

53
runMain(main);

ヘルプを見る。

サブコマンドのヘルプを見るには--helpの後ろに続けるといいらしい。試しにbyebyeを見る。

node --experimental-strip-types index.ts --help byebye

それぞれ実行してみる。

node --experimental-strip-types index.ts greet Kanon

node --experimental-strip-types index.ts byebye Kanon

setup, cleanup

setup, cleanupはrunの前後に実行する処理を定義することができる。引数にargsを指定すれば、そもそも履歴を取らなくなる。

1
  setup({ args }){
2
    console.log(`now setup ${args.command}`);
3
  },
4
  cleanup({ args }){
5
    console.log(`now cleanup ${args.command}`);
6
  },

おわりに

お気づきの方もいらっしゃるだろうが、node --experimental-strip-typesをずっと使ってTSをそのままNodeで実行している。citty自体もめっちゃシンプルで便利だけど、--experimental-strip-typesがあることで一層いい感じ。

この記事は当初はてなブログで公開したものを個人ブログ開設にあたって移植したものです。

https://blog.inorinrinrin.com/entry/2025/02/26/232548

Post to X

Share to Bluesky

UnJS製のライブラリ・cittyを使ってNode.jsでさくっとCLIを作る

citty

準備

基本

argsのtypeについて

サブコマンド

setup, cleanup

おわりに