@twin.org/cli-core 0.0.3-next.21 → 0.0.3-next.23

package/README.md

@@ -1,6 +1,6 @@
 # TWIN CLI Core
 
-Core classes for building a CLI.
+This package is part of the framework workspace and provides core classes for building a CLI to support consistent development workflows across the ecosystem.
 
 ## Installation
 
@@ -10,7 +10,7 @@ npm install @twin.org/cli-core
 
 ## Examples
 
-Usage of the tool is shown in the examples [docs/examples.md](docs/examples.md)
+Usage of the APIs is shown in the examples [docs/examples.md](docs/examples.md)
 
 ## Reference
 

package/docs/changelog.md

@@ -1,4 +1,40 @@
-# @twin.org/cli-core - Changelog
+# Changelog
+
+## [0.0.3-next.23](https://github.com/twinfoundation/framework/compare/cli-core-v0.0.3-next.22...cli-core-v0.0.3-next.23) (2026-03-17)
+
+
+### Miscellaneous Chores
+
+* **cli-core:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.22 to 0.0.3-next.23
+    * @twin.org/nameof bumped from 0.0.3-next.22 to 0.0.3-next.23
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.22 to 0.0.3-next.23
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.22 to 0.0.3-next.23
+
+## [0.0.3-next.22](https://github.com/twinfoundation/framework/compare/cli-core-v0.0.3-next.21...cli-core-v0.0.3-next.22) (2026-02-26)
+
+
+### Miscellaneous Chores
+
+* **cli-core:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.21 to 0.0.3-next.22
+    * @twin.org/nameof bumped from 0.0.3-next.21 to 0.0.3-next.22
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.21 to 0.0.3-next.22
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.21 to 0.0.3-next.22
 
 ## [0.0.3-next.21](https://github.com/twinfoundation/framework/compare/cli-core-v0.0.3-next.20...cli-core-v0.0.3-next.21) (2026-02-26)
 

package/docs/examples.md

@@ -1 +1,82 @@
-# @twin.org/cli-core - Examples
+# CLI Core Examples
+
+Use these snippets to compose clear command line workflows with consistent output, argument parsing and file handling.
+
+## CLIDisplay
+
+```typescript
+import { CLIDisplay } from '@twin.org/cli-core';
+
+CLIDisplay.header('Data Import', '1.2.0');
+CLIDisplay.section('Validation');
+CLIDisplay.value('Records', 128);
+CLIDisplay.warning('2 rows have missing optional fields');
+CLIDisplay.done();
+```
+
+## CLIParam
+
+```typescript
+import { CLIParam } from '@twin.org/cli-core';
+
+const parsedCount = CLIParam.integer('count', '25');
+const parsedDebug = CLIParam.boolean('debug', 'true');
+const parsedUrl = CLIParam.url('endpoint', 'https://api.example.org');
+
+console.log(parsedCount + 1); // 26
+console.log(parsedDebug); // true
+console.log(parsedUrl.host); // api.example.org
+```
+
+## CLIBase
+
+```typescript
+import { CLIBase } from '@twin.org/cli-core';
+import type { Command } from 'commander';
+
+class ToolCli extends CLIBase {
+  protected getCommands(program: Command): Command[] {
+    return [program.command('status').action(() => {})];
+  }
+}
+
+const cli = new ToolCli();
+const exitCode = await cli.execute(
+  {
+    appName: 'tool-cli',
+    title: 'Tool CLI',
+    version: '1.0.0'
+  },
+  './locales',
+  ['node', 'tool-cli', 'status']
+);
+
+console.log(exitCode); // 0
+```
+
+## CLIUtils
+
+```typescript
+import { CLIUtils } from '@twin.org/cli-core';
+
+console.log(await CLIUtils.fileExists('./config/import.json')); // true
+const config = await CLIUtils.readJsonFile<{ source: string }>('./config/import.json');
+await CLIUtils.writeEnvFile('./dist/import.env', {
+  SOURCE: config.source
+});
+console.log(config.source); // ./data/source.json
+```
+
+## CLIOptions
+
+```typescript
+import { CLIOptions } from '@twin.org/cli-core';
+
+const options = new CLIOptions();
+
+options.output({
+  json: './dist/output.json'
+});
+
+console.log(options.toObject().json); // ./dist/output.json
+```

package/docs/reference/classes/CLIBase.md

@@ -14,7 +14,7 @@ The main entry point for the CLI.
 
 ## Methods
 
-### execute()
+### execute() {#execute}
 
 > **execute**(`options`, `localesDirectory`, `argv`): `Promise`\<`number`\>
 
@@ -48,7 +48,7 @@ The exit code.
 
 ***
 
-### configureRoot()
+### configureRoot() {#configureroot}
 
 > `protected` **configureRoot**(`program`): `void`
 
@@ -68,7 +68,7 @@ The root program command.
 
 ***
 
-### getCommands()
+### getCommands() {#getcommands}
 
 > `protected` **getCommands**(`program`): `Command`[]
 

package/docs/reference/classes/CLIDisplay.md

@@ -14,7 +14,7 @@ Display utilities for the CLI.
 
 ## Properties
 
-### write()
+### write() {#write}
 
 > `static` **write**: (`buffer`) => `void`
 
@@ -34,7 +34,7 @@ The message to output.
 
 ***
 
-### writeError()
+### writeError() {#writeerror}
 
 > `static` **writeError**: (`buffer`) => `void`
 
@@ -54,7 +54,7 @@ The message to output.
 
 ***
 
-### clearLine()
+### clearLine() {#clearline}
 
 > `static` **clearLine**: () => `void`
 
@@ -66,7 +66,7 @@ The default output method for clearing the current line.
 
 ## Methods
 
-### header()
+### header() {#header}
 
 > `static` **header**(`title`, `version`, `icon`): `void`
 
@@ -98,9 +98,9 @@ The icon for the CLI.
 
 ***
 
-### error()
+### error() {#error}
 
-> `static` **error**(`error`, `lineBreaks`): `void`
+> `static` **error**(`error`, `lineBreaks?`): `void`
 
 Display an error message.
 
@@ -112,7 +112,7 @@ Display an error message.
 
 The error to display.
 
-##### lineBreaks
+##### lineBreaks?
 
 `boolean` = `true`
 
@@ -124,7 +124,7 @@ Whether to add a line break after the error.
 
 ***
 
-### errorMessage()
+### errorMessage() {#errormessage}
 
 > `static` **errorMessage**(`error`): `void`
 
@@ -144,7 +144,7 @@ The error to display.
 
 ***
 
-### section()
+### section() {#section}
 
 > `static` **section**(`label`): `void`
 
@@ -164,9 +164,9 @@ The label for the section.
 
 ***
 
-### value()
+### value() {#value}
 
-> `static` **value**(`label`, `value`, `indentLevel`): `void`
+> `static` **value**(`label`, `value`, `indentLevel?`): `void`
 
 Display a value with a label.
 
@@ -184,7 +184,7 @@ The label for the value.
 
 The value to display.
 
-##### indentLevel
+##### indentLevel?
 
 `number` = `0`
 
@@ -196,7 +196,7 @@ The level of indentation.
 
 ***
 
-### task()
+### task() {#task}
 
 > `static` **task**(`label`, `task?`): `void`
 
@@ -222,7 +222,7 @@ The task to display.
 
 ***
 
-### break()
+### break() {#break}
 
 > `static` **break**(): `void`
 
@@ -234,7 +234,7 @@ Display a break.
 
 ***
 
-### json()
+### json() {#json}
 
 > `static` **json**(`obj`): `void`
 
@@ -254,7 +254,7 @@ The object to display.
 
 ***
 
-### warning()
+### warning() {#warning}
 
 > `static` **warning**(`label`): `void`
 
@@ -274,7 +274,7 @@ The label for the warning.
 
 ***
 
-### done()
+### done() {#done}
 
 > `static` **done**(): `void`
 
@@ -286,27 +286,27 @@ Display the processing is done.
 
 ***
 
-### spinnerStart()
+### spinnerStart() {#spinnerstart}
 
-> `static` **spinnerStart**(`i18nMessage`, `spinnerCharacters`, `interval`): `void`
+> `static` **spinnerStart**(`i18nMessage?`, `spinnerCharacters?`, `interval?`): `void`
 
 Start the spinner.
 
 #### Parameters
 
-##### i18nMessage
+##### i18nMessage?
 
 `string` = `"cli.progress.pleaseWait"`
 
 The message to display with the spinner.
 
-##### spinnerCharacters
+##### spinnerCharacters?
 
 `string`[] = `...`
 
 The characters to use in the spinner.
 
-##### interval
+##### interval?
 
 `number` = `100`
 
@@ -318,7 +318,7 @@ The interval for the spinner.
 
 ***
 
-### spinnerStop()
+### spinnerStop() {#spinnerstop}
 
 > `static` **spinnerStop**(): `void`
 

package/docs/reference/classes/CLIOptions.md

@@ -14,7 +14,7 @@ Utilities for getting standard options.
 
 ## Methods
 
-### output()
+### output() {#output}
 
 > `static` **output**(`command`, `opts`): `void`
 

package/docs/reference/classes/CLIParam.md

@@ -14,7 +14,7 @@ Parameter utilities for the CLI.
 
 ## Methods
 
-### env()
+### env() {#env}
 
 > `static` **env**(`optionName`, `optionValue`, `allowEnvVar`): `string` \| `undefined`
 
@@ -52,9 +52,9 @@ An error if the option is invalid.
 
 ***
 
-### stringValue()
+### stringValue() {#stringvalue}
 
-> `static` **stringValue**(`optionName`, `optionValue`, `allowEnvVar`): `string`
+> `static` **stringValue**(`optionName`, `optionValue`, `allowEnvVar?`): `string`
 
 Check the option to see if the String exists.
 
@@ -72,7 +72,7 @@ The option value.
 
 `string` | `undefined`
 
-##### allowEnvVar
+##### allowEnvVar?
 
 `boolean` = `true`
 
@@ -90,9 +90,9 @@ An error if the option is invalid.
 
 ***
 
-### arrayOneOf()
+### arrayOneOf() {#arrayoneof}
 
-> `static` **arrayOneOf**\<`T`\>(`optionName`, `optionValue`, `validValues`, `allowEnvVar`): `T`
+> `static` **arrayOneOf**\<`T`\>(`optionName`, `optionValue`, `validValues`, `allowEnvVar?`): `T`
 
 Check the option to see if the value exists in the specific array.
 
@@ -122,7 +122,7 @@ The option value.
 
 The valid values.
 
-##### allowEnvVar
+##### allowEnvVar?
 
 `boolean` = `true`
 
@@ -140,9 +140,9 @@ An error if the option is invalid.
 
 ***
 
-### url()
+### url() {#url}
 
-> `static` **url**(`optionName`, `optionValue`, `allowEnvVar`): `string`
+> `static` **url**(`optionName`, `optionValue`, `allowEnvVar?`): `string`
 
 Check the option to see if it is a url.
 
@@ -160,7 +160,7 @@ The option value.
 
 `string` | `undefined`
 
-##### allowEnvVar
+##### allowEnvVar?
 
 `boolean` = `true`
 
@@ -178,9 +178,9 @@ An error if the option is invalid.
 
 ***
 
-### number()
+### number() {#number}
 
-> `static` **number**(`optionName`, `optionValue`, `allowEnvVar`, `minValue`, `maxValue?`): `number`
+> `static` **number**(`optionName`, `optionValue`, `allowEnvVar?`, `minValue?`, `maxValue?`): `number`
 
 Check the option to see if it exists and is a number.
 
@@ -198,13 +198,13 @@ The option value.
 
 `string` | `undefined`
 
-##### allowEnvVar
+##### allowEnvVar?
 
 `boolean` = `true`
 
 Allow the option to be read from an env var.
 
-##### minValue
+##### minValue?
 
 `number` = `0`
 
@@ -228,9 +228,9 @@ An error if the option is invalid.
 
 ***
 
-### integer()
+### integer() {#integer}
 
-> `static` **integer**(`optionName`, `optionValue`, `allowEnvVar`, `minValue`, `maxValue?`): `number`
+> `static` **integer**(`optionName`, `optionValue`, `allowEnvVar?`, `minValue?`, `maxValue?`): `number`
 
 Check the option to see if it exists and is an integer.
 
@@ -248,13 +248,13 @@ The option value.
 
 `string` | `undefined`
 
-##### allowEnvVar
+##### allowEnvVar?
 
 `boolean` = `true`
 
 Allow the option to be read from an env var.
 
-##### minValue
+##### minValue?
 
 `number` = `0`
 
@@ -278,9 +278,9 @@ An error if the option is invalid.
 
 ***
 
-### bigint()
+### bigint() {#bigint}
 
-> `static` **bigint**(`optionName`, `optionValue`, `allowEnvVar`, `minValue`, `maxValue?`): `bigint`
+> `static` **bigint**(`optionName`, `optionValue`, `allowEnvVar?`, `minValue?`, `maxValue?`): `bigint`
 
 Check the option to see if it exists and is a big number.
 
@@ -298,13 +298,13 @@ The option value.
 
 `string` | `undefined`
 
-##### allowEnvVar
+##### allowEnvVar?
 
 `boolean` = `true`
 
 Allow the option to be read from an env var.
 
-##### minValue
+##### minValue?
 
 `bigint` = `0n`
 
@@ -328,9 +328,9 @@ An error if the option is invalid.
 
 ***
 
-### boolean()
+### boolean() {#boolean}
 
-> `static` **boolean**(`optionName`, `optionValue`, `allowEnvVar`): `boolean`
+> `static` **boolean**(`optionName`, `optionValue`, `allowEnvVar?`): `boolean`
 
 Check the option to see if it exists and is a boolean.
 
@@ -348,7 +348,7 @@ The option value.
 
 `string` | `undefined`
 
-##### allowEnvVar
+##### allowEnvVar?
 
 `boolean` = `true`
 
@@ -366,9 +366,9 @@ An error if the option is invalid.
 
 ***
 
-### hex()
+### hex() {#hex}
 
-> `static` **hex**(`optionName`, `optionValue`, `allowEnvVar`): `Uint8Array`
+> `static` **hex**(`optionName`, `optionValue`, `allowEnvVar?`): `Uint8Array`
 
 Check the option to see if it exists and is hex.
 
@@ -386,7 +386,7 @@ The option value.
 
 `string` | `undefined`
 
-##### allowEnvVar
+##### allowEnvVar?
 
 `boolean` = `true`
 
@@ -404,9 +404,9 @@ An error if the option is invalid.
 
 ***
 
-### base64()
+### base64() {#base64}
 
-> `static` **base64**(`optionName`, `optionValue`, `allowEnvVar`): `Uint8Array`
+> `static` **base64**(`optionName`, `optionValue`, `allowEnvVar?`): `Uint8Array`
 
 Check the option to see if it exists and is base64.
 
@@ -424,7 +424,7 @@ The option value.
 
 `string` | `undefined`
 
-##### allowEnvVar
+##### allowEnvVar?
 
 `boolean` = `true`
 
@@ -442,9 +442,9 @@ An error if the option is invalid.
 
 ***
 
-### hexBase64()
+### hexBase64() {#hexbase64}
 
-> `static` **hexBase64**(`optionName`, `optionValue`, `allowEnvVar`): `Uint8Array`
+> `static` **hexBase64**(`optionName`, `optionValue`, `allowEnvVar?`): `Uint8Array`
 
 Check the option to see if it exists and is hex or base64.
 
@@ -462,7 +462,7 @@ The option value.
 
 `string` | `undefined`
 
-##### allowEnvVar
+##### allowEnvVar?
 
 `boolean` = `true`
 

package/docs/reference/classes/CLIUtils.md

@@ -14,7 +14,7 @@ Utilities function for helping in the CLI.
 
 ## Methods
 
-### fileExists()
+### fileExists() {#fileexists}
 
 > `static` **fileExists**(`filename`): `Promise`\<`boolean`\>
 
@@ -36,7 +36,7 @@ True if the file exists.
 
 ***
 
-### fileExistsSync()
+### fileExistsSync() {#fileexistssync}
 
 > `static` **fileExistsSync**(`filename`): `boolean`
 
@@ -58,7 +58,7 @@ True if the file exists.
 
 ***
 
-### dirExists()
+### dirExists() {#direxists}
 
 > `static` **dirExists**(`dir`): `Promise`\<`boolean`\>
 
@@ -80,7 +80,7 @@ True if the dir exists.
 
 ***
 
-### dirExistsSync()
+### dirExistsSync() {#direxistssync}
 
 > `static` **dirExistsSync**(`dir`): `boolean`
 
@@ -102,7 +102,7 @@ True if the dir exists.
 
 ***
 
-### readJsonFile()
+### readJsonFile() {#readjsonfile}
 
 > `static` **readJsonFile**\<`T`\>(`filename`): `Promise`\<`T` \| `undefined`\>
 
@@ -130,7 +130,7 @@ The parsed JSON.
 
 ***
 
-### readJsonFileSync()
+### readJsonFileSync() {#readjsonfilesync}
 
 > `static` **readJsonFileSync**\<`T`\>(`filename`): `T` \| `undefined`
 
@@ -158,7 +158,7 @@ The parsed JSON.
 
 ***
 
-### readLinesFile()
+### readLinesFile() {#readlinesfile}
 
 > `static` **readLinesFile**(`filename`): `Promise`\<`string`[] \| `undefined`\>
 
@@ -180,7 +180,7 @@ The lines.
 
 ***
 
-### readLinesFileSync()
+### readLinesFileSync() {#readlinesfilesync}
 
 > `static` **readLinesFileSync**(`filename`): `string`[] \| `undefined`
 
@@ -202,7 +202,7 @@ The lines.
 
 ***
 
-### findNpmRoot()
+### findNpmRoot() {#findnpmroot}
 
 > `static` **findNpmRoot**(`rootFolder`): `Promise`\<`string`\>
 
@@ -224,7 +224,7 @@ The root path.
 
 ***
 
-### runShellCmd()
+### runShellCmd() {#runshellcmd}
 
 > `static` **runShellCmd**(`command`, `args`, `cwd`): `Promise`\<`void`\>
 
@@ -258,7 +258,7 @@ Promise to wait for command execution to complete.
 
 ***
 
-### runShellApp()
+### runShellApp() {#runshellapp}
 
 > `static` **runShellApp**(`app`, `args`, `cwd`): `Promise`\<`void`\>
 
@@ -292,7 +292,7 @@ Promise to wait for command execution to complete.
 
 ***
 
-### writeJsonFile()
+### writeJsonFile() {#writejsonfile}
 
 > `static` **writeJsonFile**\<`T`\>(`jsonFilename`, `data`, `append`): `Promise`\<`void`\>
 
@@ -330,7 +330,7 @@ Append to the file.
 
 ***
 
-### writeEnvFile()
+### writeEnvFile() {#writeenvfile}
 
 > `static` **writeEnvFile**(`envFilename`, `data`, `append`): `Promise`\<`void`\>
 

package/docs/reference/interfaces/ICliOptions.md

@@ -4,7 +4,7 @@ Options for the CLI.
 
 ## Properties
 
-### title
+### title {#title}
 
 > **title**: `string`
 
@@ -12,7 +12,7 @@ The title of the CLI.
 
 ***
 
-### appName
+### appName {#appname}
 
 > **appName**: `string`
 
@@ -20,7 +20,7 @@ The name of the app used to execute it.
 
 ***
 
-### version
+### version {#version}
 
 > **version**: `string`
 
@@ -28,7 +28,7 @@ The version of the app.
 
 ***
 
-### icon
+### icon {#icon}
 
 > **icon**: `string`
 
@@ -36,7 +36,7 @@ The icon for the CLI as an emoji character.
 
 ***
 
-### supportsLang?
+### supportsLang? {#supportslang}
 
 > `optional` **supportsLang**: `boolean`
 
@@ -44,7 +44,7 @@ Supports different languages.
 
 ***
 
-### supportsEnvFiles?
+### supportsEnvFiles? {#supportsenvfiles}
 
 > `optional` **supportsEnvFiles**: `boolean`
 
@@ -52,7 +52,7 @@ Supports the loading of env files.
 
 ***
 
-### overrideOutputWidth?
+### overrideOutputWidth? {#overrideoutputwidth}
 
 > `optional` **overrideOutputWidth**: `number`
 
@@ -60,7 +60,7 @@ Override the default output width.
 
 ***
 
-### showDevToolWarning?
+### showDevToolWarning? {#showdevtoolwarning}
 
 > `optional` **showDevToolWarning**: `boolean`
 

package/docs/reference/interfaces/ICliOutputOptionsConsole.md

@@ -4,7 +4,7 @@ Options for the CLI Output for console.
 
 ## Properties
 
-### console
+### console {#console}
 
 > **console**: `boolean`
 

package/docs/reference/interfaces/ICliOutputOptionsEnv.md

@@ -4,7 +4,7 @@ Options for the CLI Output for env.
 
 ## Properties
 
-### env?
+### env? {#env}
 
 > `optional` **env**: `string`
 
@@ -12,7 +12,7 @@ Output the data to an environment file.
 
 ***
 
-### mergeEnv
+### mergeEnv {#mergeenv}
 
 > **mergeEnv**: `boolean`
 

package/docs/reference/interfaces/ICliOutputOptionsJson.md

@@ -4,7 +4,7 @@ Options for the CLI Output for JSON.
 
 ## Properties
 
-### json?
+### json? {#json}
 
 > `optional` **json**: `string`
 
@@ -12,7 +12,7 @@ Output the data to an JSON file.
 
 ***
 
-### mergeJson
+### mergeJson {#mergejson}
 
 > **mergeJson**: `boolean`
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/cli-core",
-	"version": "0.0.3-next.21",
+	"version": "0.0.3-next.23",
 	"description": "Core classes for building a CLI",
 	"repository": {
 		"type": "git",
@@ -14,11 +14,11 @@
 		"node": ">=20.0.0"
 	},
 	"dependencies": {
-		"@twin.org/core": "0.0.3-next.21",
-		"@twin.org/nameof": "0.0.3-next.21",
+		"@twin.org/core": "0.0.3-next.23",
+		"@twin.org/nameof": "0.0.3-next.23",
 		"chalk": "5.6.2",
-		"commander": "14.0.2",
-		"dotenv": "17.2.3"
+		"commander": "14.0.3",
+		"dotenv": "17.3.1"
 	},
 	"main": "./dist/es/index.js",
 	"types": "./dist/types/index.d.ts",