@snailicide/cli-app 🐌

Node Cli App Boilerplate with yargs, zod, chalk

---

• Github: @snailicide/cli-app • snailicide-monorepo
• CDN: jsdeliver

Author

👤 Gillian Tunney

• github
• email

Recommended package manager is pnpm

@snailicide/cli-app 🐌

---

The @snailicide/cli-app package is a builder application for making custom command-line interface (CLI) application. Developers can quickly bootstrap a boilerplate with powerful validation/parsing schemas. It leverages several libraries to provide robust and interactive user experience.

Key Features

• Command-Line Parsing: Utilizes yargs and yargs-interactive for parsing command-line arguments and handling interactive prompts.
• Schema Validation/Handling: Use zod schemas to parse/validate input, including resolving user options & application configurations, and generating Yargs-compatible option objects.
• Configuration Management: Manages application configurations using schemas defined with zod. This ensures that configurations are validated and adhere to expected structures.
• Title /HelpScreen Management: Manage custom cli options and customize appearance of title/help menu terminal output.

---

Installation

This library is published in the NPM registry and can be installed using any compatible package manager as a development dependency.

1#pnpm
2pnpm add @snailicide/cli-app
3
4#yarn
5yarn add @snailicide/cli-app
6
7#npm
8npm install @snailicide/cli-app

Example Usage

The cli-app package can be initialized and configured using the initApp function, which sets up the application based on provided schemas and options, and supports interactive prompts if needed.

---

1import { z } from 'zod'
2
3import {
4  AppConfigIn,
5  commonFlagsSchema,
6  initApp,
7  InitSuccessCallback,
8  WrappedSchema,
9  wrapSchema,
10} from './index.js'
11
12/** Define custom schema, wrapper is required to avoid typescript error */
13const custom_schema = z.object({
14  testarr: z.number().array().default([]).describe('test array'),
15  testarr2: z.string().array().default([]).describe('test array'),
16})
17const my_merged_schema = wrapSchema<typeof commonFlagsSchema>(commonFlagsSchema)
18  .merge(custom_schema)
19  .transform((value) => {
20    return value
21  })
22  .describe('this is a sample app that is made of fun')
23
24type MergedSchema = WrappedSchema<typeof my_merged_schema>
25
26/** Set the init function which will be called after app is intialized with typed arguments. */
27const initFunc: InitSuccessCallback<MergedSchema> = <
28  Schema extends
29    | z.AnyZodObject
30    | z.ZodEffects<z.AnyZodObject> = typeof commonFlagsSchema,
31>(
32  args: z.infer<Schema>,
33) => {
34  if (args['testarr']) {
35    console.warn('RESOLVED APP ARGS: ', args)
36  }
37  console.log(JSON.stringify(args))
38  return true
39}
40
41/** Example app configuration options */
42const exampleAppConfigOptions: AppConfigIn<MergedSchema> = {
43  description: 'This is an example to demonstrate use',
44  //code editor error
45  examples: [
46    ['$0 --config "~/config.json"', 'Use custom config'],
47    ['$0 --safe', 'Start in safe mode'],
48  ],
49  flag_aliases: {
50    outDir: 'o',
51    rootDir: 'r',
52    // help: 'h',
53    //version: 'v',
54  },
55  hidden: ['debug', 'testarr2'],
56  name: 'Example App',
57}
58
59/** Initialize App */
60const initialize = async (): Promise<'SUCCESS' | 'ERROR'> => {
61  const instance_yargs = await initApp<MergedSchema>(
62    my_merged_schema,
63    exampleAppConfigOptions,
64    initFunc,
65  )
66  if (instance_yargs === undefined) {
67    process.exit(1)
68    return 'ERROR'
69  }
70  process.exit(0)
71  return 'SUCCESS'
72}
73
74export default initialize()

Helpful Links

• yargs
• yargs-interactive
• zod
• chalk
• figlet