Guide

Installation

@xpulse/cli is installed locally in the project – no global install needed.

1 npm install @xpulse/cli

Important: The project's package.json must include "type": "module", as the entire xPulse ecosystem uses ESM (import/export):

1 {
2   "name": "my-project",
3   "type": "module",
4   "dependencies": {
5     "@xpulse/cli": "^1.0.0"
6   }
7 }

Usage – always with `npx`

@xpulse/cli is always called via npx. This uses the local version from node_modules/.bin/xpulse – consistent, reproducible, no version mismatch with globally installed versions.

1 npx xpulse --version
2 npx xpulse --list
3 npx xpulse --help
4 npx xpulse --help tapp:hello
5 npx xpulse tapp:hello --help
6 npx xpulse tapp:hello Johnny -lang="en" --shout

How does it work?

@xpulse/cli starts and automatically discovers all Command classes:

1 npx xpulse doc:fetch chat --dry-run
2   ↓
3 @xpulse/cli discovers:
4   1. node_modules/@xpulse/*/src/commands/*.js  ← installed xParts
5   2. src/commands/*.js                          ← local project
6  
7   → finds FetchCommand (name = 'doc:fetch')
8   → builds Input + Output, injects keepAlive
9   → new FetchCommand().run(input, output)
10   ↓
11 FetchCommand.run() executes → return 0
12   ↓
13 @xpulse/cli → process.exit(0)

Writing a command

Create a file under src/commands/, extend Command – done. @xpulse/cli finds it automatically.

1 // src/commands/HelloCommand.js
2 import { Command } from '@xpulse/cli/command';
3  
4 export class HelloCommand extends Command {
5  
6     configure() {
7         this
8             .setName('tapp:hello')
9             .setAlias('hi')
10             .setDescription('Say hello')
11             .setHelp('Prints a greeting message to the console.')
12             .addArgument('name',  'Anon', 'Name of the recipient')
13             .addOption('lang',    'de',   'Language (de/en)')
14             .addFlag('shout',     false,  'Output in uppercase');
15     }
16  
17     async run(input, output) {
18         const name  = input.getArgument('name');
19         const shout = input.getFlag('shout');
20         let msg     = `Hello ${name}!`;
21  
22         if (shout) msg = msg.toUpperCase();
23         output.success(msg);
24         return 0;
25     }
26 }

No import event, no cli:done – just return an exit code.

Argument vs. Option vs. Flag

Type	Definition	Usage
Argument	`addArgument('name', ...)`	`npx xpulse cmd Johnny` (positional)
Option	`addOption('lang', ...)`	`npx xpulse cmd -lang="en"`
Flag	`addFlag('shout', ...)`	`npx xpulse cmd --shout`

Important: Options must always use =:

1 npx xpulse tapp:hello -lang="en"    # ✓ correct
2 npx xpulse tapp:hello --lang="en"   # ✓ correct
3 npx xpulse tapp:hello -lang en      # ✗ warning – "en" treated as positional argument
4 npx xpulse tapp:hello --lang en     # ✗ warning – "en" treated as positional argument

When using incorrect syntax, @xpulse/cli outputs a warning:

1 ! Invalid syntax: "--lang en" – did you mean --lang="en"?
2   "en" is treated as a positional argument.

Exit codes

Code	Meaning
`0`	Success
`1`	Error
`2`	Misuse – wrong or missing arguments

Long-running commands

Commands that run longer than CLI_TIMEOUT (default: 30s) call this.keepAlive() periodically to reset the timeout:

1 async run(input, output) {
2     while (!done) {
3         await doWork();
4         this.keepAlive(); // reset timeout – no event import needed
5     }
6     return 0;
7 }

Configure timeout

1 CLI_TIMEOUT=60 npx xpulse repo:changelog:generate

1	{
2	"name": "my-project",
3	"type": "module",
4	"dependencies": {
5	"@xpulse/cli": "^1.0.0"
6	}
7	}

1	npx xpulse --version
2	npx xpulse --list
3	npx xpulse --help
4	npx xpulse --help tapp:hello
5	npx xpulse tapp:hello --help
6	npx xpulse tapp:hello Johnny -lang="en" --shout

1	npx xpulse doc:fetch chat --dry-run
2	↓
3	@xpulse/cli discovers:
4	1. node_modules/@xpulse//src/commands/.js ← installed xParts
5	2. src/commands/*.js ← local project
6
7	→ finds FetchCommand (name = 'doc:fetch')
8	→ builds Input + Output, injects keepAlive
9	→ new FetchCommand().run(input, output)
10	↓
11	FetchCommand.run() executes → return 0
12	↓
13	@xpulse/cli → process.exit(0)

1	// src/commands/HelloCommand.js
2	import { Command } from '@xpulse/cli/command';
3
4	export class HelloCommand extends Command {
5
6	configure() {
7	this
8	.setName('tapp:hello')
9	.setAlias('hi')
10	.setDescription('Say hello')
11	.setHelp('Prints a greeting message to the console.')
12	.addArgument('name', 'Anon', 'Name of the recipient')
13	.addOption('lang', 'de', 'Language (de/en)')
14	.addFlag('shout', false, 'Output in uppercase');
15	}
16
17	async run(input, output) {
18	const name = input.getArgument('name');
19	const shout = input.getFlag('shout');
20	let msg = `Hello ${name}!`;
21
22	if (shout) msg = msg.toUpperCase();
23	output.success(msg);
24	return 0;
25	}
26	}

1	npx xpulse tapp:hello -lang="en" # ✓ correct
2	npx xpulse tapp:hello --lang="en" # ✓ correct
3	npx xpulse tapp:hello -lang en # ✗ warning – "en" treated as positional argument
4	npx xpulse tapp:hello --lang en # ✗ warning – "en" treated as positional argument

1	! Invalid syntax: "--lang en" – did you mean --lang="en"?
2	"en" is treated as a positional argument.

1	async run(input, output) {
2	while (!done) {
3	await doWork();
4	this.keepAlive(); // reset timeout – no event import needed
5	}
6	return 0;
7	}