Pastel

Pastel treats every file in the commands folder as a command. The filename (excluding extension) becomes the command name. Each command file must export a React component that renders the command's output.

To define type-safe options and arguments, export an options object created with zod. The component receives these options as props.

Example command (commands/login.tsx):

import React from 'react';
import {Text} from 'ink';

export default function Login() {
	return <Text>Logging in</Text>;
}

Pastel wraps every command component with a component exported from commands/_app.tsx. If this file exists, you can use it to inject shared logic, context, or styling across all commands in your CLI.

If _app.tsx is missing, Pastel uses a default component that simply renders your command with options and args props.

import React from 'react';
import type {AppProps} from 'pastel';

export default function App({Component, commandProps}: AppProps) {
	// Add shared logic here
	return <Component {...commandProps} />;
}

Files named index.tsx inside the commands folder are treated as index commands. They are executed when the CLI is run without any specific command name.

This is ideal for single-purpose CLIs.

Example structure:

commands/
	index.tsx
	login.tsx

Running my-cli will execute index.tsx.

To group related commands, create nested folders within the commands directory. The folder name becomes the first part of the command, and the filename becomes the second.

Example structure:

commands/
	domains/
		list.tsx
		add.tsx

This allows users to run my-cli domains list or my-cli domains add.

Arguments in Pastel are positional values that do not require flags (e.g., --name). They are defined using Zod schemas and passed to the command component via the args prop.

• Fixed number of arguments: Use zod.tuple([...]) when the exact number and order of arguments matter (e.g., a mv command).
• Variable number of arguments: Use zod.array(...) when a command can accept any number of arguments (e.g., an rm command).

The fastest way to get started is using the create-pastel-app scaffolding tool, which sets up a TypeScript project with a linter and tests pre-configured.

npm create pastel-app hello-world
cd hello-world

You can define default values for arguments using Zod's .default() method. These values will be automatically used if the user does not provide the argument, and the default value will be displayed in the --help output.

If you want the help message to show a formatted version of the default (e.g., adding commas to a large number), use the defaultValueDescription option within the argument() helper.

export const args = zod.tuple([
	zod
		.number()
		.default(1024)
		.describe(
			argument({
				name: 'number',
				description: 'Some number',
				defaultValueDescription: '1,024',
			}),
		),
]);

To use Pastel in your project, you need to install pastel along with ink (the rendering engine) and zod (for type-safe options and arguments).

npm install pastel ink zod

When a boolean option is configured with a default value of true, Pastel automatically supports a negated flag by adding the no- prefix to the option name. This allows users to explicitly set the value to false.

import React from 'react';
import {Text} from 'ink';
import zod from 'zod';

export const options = zod.object({
	compress: zod.boolean().default(true).describe("Don't compress output"),
});

type Props = {
	options: zod.infer<typeof options>;
};

export default function Example({options}: Props) {
	return <Text>Compress = {String(options.compress)}</Text>;
}

Usage:

$ my-cli --no-compress
Compress = false

By default, all options defined in a Zod schema are required. To make an option optional (so the command can run without it), use the .optional() method in your Zod schema.

import React from 'react';
import {Text} from 'ink';
import zod from 'zod';

export const options = zod.object({
	os: zod.enum(['Ubuntu', 'Debian']).optional().describe('Operating system'),
});

type Props = {
	options: zod.infer<typeof options>;
};

export default function Example({options}: Props) {
	return <Text>Operating system = {options.os ?? 'unspecified'}</Text>;
}