effect-cli

Effect CLI (v4)

Build type-safe command-line applications with typed arguments, flags, subcommands, and dependency injection.

Import Pattern

import { Argument, Command, Flag, Prompt } from 'effect/unstable/cli';

Platform services and runtime for the entry point:

import { NodeRuntime, NodeServices } from '@effect/platform-node';

Positional Arguments (Argument)

Positional arguments are parsed in order. Argument.boolean intentionally does not exist — use Flag.boolean or Argument.choice("name", ["true", "false"]) instead.

Constructors

import { Argument } from 'effect/unstable/cli';

Argument.string('name'); // string
Argument.integer('count'); // number (integer)
Argument.float('ratio'); // number (float)
Argument.date('deadline'); // Date
Argument.file('input'); // file path (string)
Argument.file('input', { mustExist: true }); // file path that must exist
Argument.directory('dir'); // directory path (string)
Argument.directory('dir', { mustExist: true }); // directory that must exist
Argument.path('target'); // any path (string)
Argument.choice('env', ['dev', 'staging', 'prod']); // constrained string union
Argument.choiceWithValue('level', [
	// choice with mapped values
	['debug', 0],
	['info', 1],
	['error', 3]
]);
Argument.redacted('secret'); // Redacted<string>
Argument.fileText('config'); // reads file content as string
Argument.fileParse('config'); // reads and parses file (auto-detects format)
Argument.fileSchema('config', MySchema); // reads and validates file via Schema

Combinators

import { Argument } from 'effect/unstable/cli';

// Description for help text
Argument.string('file').pipe(Argument.withDescription('Input file'));

// Default value
Argument.integer('port').pipe(Argument.withDefault(8080));

// Optional (returns Option<T>)
Argument.string('config').pipe(Argument.optional);

// Variadic (returns ReadonlyArray<T>)
Argument.string('files').pipe(Argument.variadic);
Argument.string('files').pipe(Argument.variadic({ min: 1 }));
Argument.string('files').pipe(Argument.variadic({ min: 1, max: 5 }));

// Direct variadic form is also supported
Argument.variadic(Argument.string('files'));
Argument.variadic(Argument.string('files'), { min: 1 });

// Cardinality shortcuts
Argument.string('files').pipe(Argument.atLeast(1));
Argument.string('files').pipe(Argument.atMost(5));
Argument.string('files').pipe(Argument.between(1, 5));

// Transform
Argument.integer('port').pipe(Argument.map((p) => `http://localhost:${p}`));

// Validate with Schema
Argument.string('input').pipe(Argument.withSchema(Schema.NonEmptyString));

// Fallback from env config
Argument.string('repo').pipe(
	Argument.withFallbackConfig(Config.string('REPOSITORY'))
);

// Fallback interactive prompt
Argument.string('name').pipe(
	Argument.withFallbackPrompt(Prompt.text({ message: 'Name' }))
);

// Custom metavar for help text
Argument.integer('port').pipe(Argument.withMetavar('PORT'));

// Filter with error message
Argument.integer('count').pipe(
	Argument.filter(
		(n) => n > 0,
		(n) => `Expected positive, got ${n}`
	)
);