# @bpinternal/yargs-extra

> Utils functions that leverage yargs.

Latest version **0.0.21** (published 2025-07-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install @bpinternal/yargs-extra
pnpm add @bpinternal/yargs-extra
yarn add @bpinternal/yargs-extra
bun add @bpinternal/yargs-extra
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 0.0.21 |
| Published | 2025-07-18 |
| First published | 2022-06-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=16.0.0 |
| Dependencies | 6 |
| Unpacked size | 103.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 19 |
| Author | Botpress, Inc. |
| Maintainers | allardy, davidvitora, michael.masson, franklevasseur, chsir17, slvnperron, botpress-cloud-ops |

## Links

- npm: https://www.npmjs.com/package/@bpinternal/yargs-extra
- Repository: https://github.com/botpress/packages
- Homepage: https://github.com/botpress/packages#readme
- Issues: https://github.com/botpress/packages/issues
- npm.io page: https://npm.io/package/@bpinternal/yargs-extra

## Dependencies (6)

- [yn](https://npm.io/package/yn.md) 4.0.0
- [yargs](https://npm.io/package/yargs.md) ^17.7.2
- [lodash](https://npm.io/package/lodash.md) ^4.17.21
- [decamelize](https://npm.io/package/decamelize.md) 5.0.1
- [json-schema](https://npm.io/package/json-schema.md) ^0.4.0
- [@types/yargs](https://npm.io/package/@types/yargs.md) ^17.0.32

## Recent versions

- 0.0.21 (latest) — 2025-07-18
- 0.0.20 — 2025-04-01
- 0.0.19 — 2025-02-07
- 0.0.18 — 2025-02-04
- 0.0.17 — 2024-11-11
- 0.0.16 — 2024-10-21
- 0.0.15 — 2024-10-16
- 0.0.14 — 2024-10-07
- 0.0.13 — 2024-09-26
- 0.0.12 — 2024-09-25
- 0.0.11 — 2024-07-18
- 0.0.10 — 2024-07-02
- 0.0.9 — 2024-06-10
- 0.0.8 — 2024-05-31
- 0.0.7 — 2024-05-01
- … 6 more at https://npm.io/package/@bpinternal/yargs-extra/versions

## README

# Yargs Extra

Few additions to the library [yargs](https://github.com/yargs/yargs) including the ability to parse environment variables and create a json-schema from yargs options.

## Usage

Your TypeScript program could look like this:

```ts
import os from 'os'
import path from 'path'
import fs from 'fs'
import yargs, { asYargs, generateSchema, cleanupConfig, parseEnv } from '@bpinternal/yargs-extra'

const yargsSchema = asYargs({
  remoteUrl: {
    type: 'string',
    description: 'URL to remote server'
  },
  oauth: {
    type: 'boolean',
    description: 'Whether or not to use oauth'
  }
})

const jsonSchemaLocation = path.join(os.homedir(), '.myapp', 'myapp.config.schema.json')
const configFileLocation = path.join(process.cwd(), 'myapp.config.json')

const stringify = (x) => JSON.stringify(x, null, 2)

void yargs
  .command(
    'init',
    'Init configuration file',
    (yargs) => yargs.options({}),
    async () => {
      const jsonSchema = generateSchema(yargsSchema)
      fs.writeFileSync(jsonSchemaLocation, stringify(jsonSchema))
      fs.writeFileSync(configFileLocation, stringify({ $schema: jsonSchemaLocation }))
    }
  )
  .command(
    'build',
    'Build something',
    (yargs) => yargs.options(yargsSchema),
    async (yargsArgv) => {
      const yargsEnv = parseEnv(yargsSchema, 'MYAPP')
      const yargsFile = fs.existsSync(configFileLocation)
        ? JSON.parse(fs.readFileSync(configFileLocation, 'utf-8'))
        : undefined

      // cli args will override json config, which will also override env variables
      const resolved = cleanupConfig(yargsSchema, { ...yargsEnv, ...yargsFile, ...yargsArgv })
      console.log(resolved)

      // ...
    }
  )
  .help().argv
```

Using this program above, you can try out few different ways of passing arguments:

```bash
./myapp init # will create an empty config file
code ./myapp.config.json # will open your config file in vscode with intellisense

MYAPP_REMOTE_URL=http://lol.com ./myapp build # { remoteUrl: 'http://lol.com' }
MYAPP_REMOTE_URL=http://lol.com ./myapp build --oauth # { remoteUrl: 'http://lol.com', oauth: true }
MYAPP_REMOTE_URL=http://lol.com ./myapp build --remote-url http://localhost:3100 # { remoteUrl: 'http://localhost:3100' }
```

When opening the config file in vscode, you'll get intellisense:

![config file](./readme.png)

## Disclaimer ⚠️

This package is published under the `@bpinternal` organization. All packages of this organization are meant to be used by the [Botpress](https://github.com/botpress/botpress) team internally and are not meant for our community. Since the packages are catered to our own use-cases, they might have less stable APIs, receive breaking changes without much warning, have minimal documentation and lack community-focused support. However, these packages were still left intentionally public for an important reason : We Love Open-Source. Therefore, if you wish to install or fork this package feel absolutly free to do it. We strongly recommend that you tag your versions properly.

The Botpress Engineering team.

---
_Source: https://npm.io/package/@bpinternal/yargs-extra · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._