API

Command class

1 import { Command } from '@xpulse/cli/command';

`configure()`

Called in the constructor. Fully describes the command. Override in your subclass.

1 configure() {
2     this
3         .setName('doc:fetch')
4         .setAlias('df')
5         .setDescription('Fetch docs via git archive')
6         .setHelp('Fetches docs from an xPulse repo and stores them locally.')
7         .addArgument('tool',      null,    'Tool name (e.g. chat)')
8         .addOption('tag',         null,    'Git tag to fetch')
9         .addOption('output-dir',  './docs','Target directory')
10         .addFlag('dry-run',       false,   'Simulate only, write nothing');
11 }

Fluent setters

Method	Description
`setName(name)`	Command name – `namespace:area:command`
`setAlias(alias)`	Short name shown in `--list` and `--help`
`setDescription(text)`	Short description for `--list` and `--help`
`setHelp(text)`	Longer text shown in `--help <command>`
`addArgument(name, default, description)`	Positional argument
`addOption(name, default, description)`	Named option (`-key="value"`)
`addFlag(name, default, description)`	Boolean flag (`--flag`)

All setters return this – fully chainable.

`run(input, output)` → `Promise`

Must be implemented by the subclass. Returns an exit code.

1 async run(input, output) {
2     // ...
3     return 0; // 0 = success, 1 = error, 2 = misuse
4 }

`keepAlive()`

Resets the timeout timer. For long-running commands. No import of @xpulse/event needed – injected by @xpulse/cli.

1 async run(input, output) {
2     while (!done) {
3         await doWork();
4         this.keepAlive();
5     }
6     return 0;
7 }

Input class

1 import { Input } from '@xpulse/cli/input';

Built by @xpulse/cli and passed to run().

Positional arguments

1 input.getArgument('tool')   // → 'chat' | default | null

Positional arguments are matched by the order of addArgument() calls.

Named options

1 input.getOption('tag')        // → 'v1.3.0' | default | null
2 input.getOption('output-dir') // kebab-case
3 input.getOption('outputDir')  // camelCase – equivalent
4 input.hasOption('tag')        // → true | false

Boolean flags

1 input.getFlag('dry-run')  // kebab-case
2 input.getFlag('dryRun')   // camelCase – equivalent

Global flags

Method	Flag	Shortcut
`input.isVerbose()`	`--verbose`	`-V`
`input.isQuiet()`	`--quiet`	`-q`
`input.isAnsi()`	`--no-ansi` negated	–
`input.isNoDebug()`	`--no-debug`	–

Output class

1 import { Output } from '@xpulse/cli/output';

Built by @xpulse/cli and passed to run(). Respects --no-ansi and --quiet automatically.

Method	Description
`output.write(text)`	Text without newline
`output.writeln(text?)`	Text with newline
`output.success(text)`	`✓` green
`output.warn(text)`	`!` yellow
`output.error(text)`	`✗` red – ignores `--quiet`
`output.table(headers, rows)`	Formatted table

CLI flags

Flag	Shortcut	Description
`--help [command]`	`-h`	CLI help, or command help if name given
`--list`	–	All commands with alias and description
`--version`	`-v`	Print version
`--verbose`	`-V`	Verbose output → `input.isVerbose()`
`--quiet`	`-q`	Errors only → `input.isQuiet()`
`--no-ansi`	–	No colors → `input.isAnsi() = false`
`--no-debug`	–	Logger console level raised to `warn` – info/debug suppressed on console, file log unaffected

`--help` variants

Both are equivalent:

1 npx xpulse --help tapp:hello   # flag before command name
2 npx xpulse tapp:hello --help   # flag after command name

Argument parser

Rules

Syntax	Result
`namespace:area:command`	Command name
`value` (no prefix)	Positional argument → `rawArguments[]`
`-key="value"` / `-key=value`	`{ key: 'value' }`
`--key="value"` / `--key=value`	`{ key: 'value' }` (camelCase)
`-flag`	`{ flag: true }`
`--flag` / `--dry-run`	`{ dryRun: true }` (camelCase)
`-key value` / `--key value`	⚠ Warning – `value` treated as positional
`--verbose` / `-V`	Global flag
`--quiet` / `-q`	Global flag
`--no-ansi`	Global flag
`--no-debug`	Global flag

Example

1 npx xpulse doc:fetch chat -tag="v1.3.0" --dry-run -V
2 → {
3     name:         'doc:fetch',
4     args:         { tag: 'v1.3.0', dryRun: true },
5     rawArguments: ['chat'],
6     verbose:      true,
7     quiet:        false,
8     ansi:         true,
9     warnings:     [],
10   }

Bootstrap

Before running a command, @xpulse/cli calls app.init() from @xpulse/app if it is installed. This gives every command full service context (config, logger, debug, router, controller) without starting the HTTP server.

If @xpulse/app is not installed, config.load() is called as a fallback.

Environment variables

Variable	Default	Description
`CLI_TIMEOUT`	`30`	Timeout in seconds before exit code `1`

1	configure() {
2	this
3	.setName('doc:fetch')
4	.setAlias('df')
5	.setDescription('Fetch docs via git archive')
6	.setHelp('Fetches docs from an xPulse repo and stores them locally.')
7	.addArgument('tool', null, 'Tool name (e.g. chat)')
8	.addOption('tag', null, 'Git tag to fetch')
9	.addOption('output-dir', './docs','Target directory')
10	.addFlag('dry-run', false, 'Simulate only, write nothing');
11	}

1	async run(input, output) {
2	// ...
3	return 0; // 0 = success, 1 = error, 2 = misuse
4	}

1	async run(input, output) {
2	while (!done) {
3	await doWork();
4	this.keepAlive();
5	}
6	return 0;
7	}

1	input.getOption('tag') // → 'v1.3.0' \| default \| null
2	input.getOption('output-dir') // kebab-case
3	input.getOption('outputDir') // camelCase – equivalent
4	input.hasOption('tag') // → true \| false

1	input.getFlag('dry-run') // kebab-case
2	input.getFlag('dryRun') // camelCase – equivalent

1	npx xpulse --help tapp:hello # flag before command name
2	npx xpulse tapp:hello --help # flag after command name

1	npx xpulse doc:fetch chat -tag="v1.3.0" --dry-run -V
2	→ {
3	name: 'doc:fetch',
4	args: { tag: 'v1.3.0', dryRun: true },
5	rawArguments: ['chat'],
6	verbose: true,
7	quiet: false,
8	ansi: true,
9	warnings: [],
10	}