HelpDoc unstable

Structured help documentation model for the unstable CLI package. A HelpDoc value captures the user-facing parts of a command, including its description, usage string, positional arguments, flags, global flags, subcommands, annotations, and examples.

This module only defines the data shapes used to describe help. Rendering that data as terminal text is handled by CliOutput.

6 exports Since v4.0.0 Source

Models

ArgDoc

interface unstable

Since v4.0.0

Documentation for a positional argument

Signature

interface ArgDoc {
  readonly description: Option<string>;
  readonly name: string;
  readonly required: boolean;
  readonly type: string;
  readonly variadic: boolean;
}

Example Documenting positional arguments

import { Context, Option as O } from "effect"
import type { HelpDoc } from "effect/cli"

const sourceArg: HelpDoc.ArgDoc = {
  name: "source",
  type: "file",
  description: O.some("Source file to process"),
  required: true,
  variadic: false
}

const filesArg: HelpDoc.ArgDoc = {
  name: "files",
  type: "file",
  description: O.some("Files to process (can specify multiple)"),
  required: false,
  variadic: true
}

// Used in command help documentation
const copyCommandHelp: HelpDoc.HelpDoc = {
  description: "Copy files from source to destination",
  usage: "copy <source> [files...]",
  annotations: Context.empty(),
  flags: [],
  args: [sourceArg, filesArg]
}

copyCommandHelp.args?.map((arg) => arg.name) // => ["source", "files"]

ExampleDoc

interface unstable

Since v4.0.0

Documentation for a command usage example

Signature

interface ExampleDoc {
  readonly command: string;
  readonly description?: string;
}

FlagDoc

interface unstable

Since v4.0.0

Documentation for a single command-line flag/option

Signature

interface FlagDoc {
  readonly aliases: readonly Array<string>;
  readonly description: Option<string>;
  readonly name: string;
  readonly required: boolean;
  readonly type: string;
}

Example Documenting command flags

import { Option as O } from "effect"
import type { HelpDoc } from "effect/cli"

const verboseFlag: HelpDoc.FlagDoc = {
  name: "verbose",
  aliases: ["-v", "--verbose"],
  type: "boolean",
  description: O.some("Enable verbose output"),
  required: false
}

const portFlag: HelpDoc.FlagDoc = {
  name: "port",
  aliases: ["-p"],
  type: "integer",
  description: O.some("Port number to use"),
  required: true
}

const names = [verboseFlag.name, portFlag.name] // => ["verbose", "port"]

HelpDoc

interface unstable

Since v4.0.0

Structured representation of help documentation for a command. This data structure is independent of formatting, allowing for different output formats (text, markdown, JSON, etc.).

Signature

interface HelpDoc {
  readonly annotations: Context<never>;
  readonly args?: readonly Array<ArgDoc>;
  readonly description: string;
  readonly examples?: readonly Array<ExampleDoc>;
  readonly flags: readonly Array<FlagDoc>;
  readonly globalFlags?: readonly Array<FlagDoc>;
  readonly subcommands?: readonly Array<SubcommandGroupDoc>;
  readonly usage: string;
}

Example Defining command help documentation

import { Context, Option as O } from "effect"
import type { HelpDoc } from "effect/cli"

const deployCommandHelp: HelpDoc.HelpDoc = {
  description: "Deploy your application to the cloud",
  usage: "myapp deploy [options] <target>",
  annotations: Context.empty(),
  flags: [
    {
      name: "verbose",
      aliases: ["-v"],
      type: "boolean",
      description: O.some("Enable verbose logging"),
      required: false
    },
    {
      name: "env",
      aliases: ["-e"],
      type: "string",
      description: O.some("Target environment"),
      required: true
    }
  ],
  args: [
    {
      name: "target",
      type: "string",
      description: O.some("Deployment target (e.g., 'production', 'staging')"),
      required: true,
      variadic: false
    }
  ]
}

deployCommandHelp.usage // => "myapp deploy [options] <target>"

SubcommandDoc

interface unstable

Since v4.0.0

Documentation for a subcommand

Signature

interface SubcommandDoc {
  readonly alias: string | undefined;
  readonly description: string;
  readonly name: string;
  readonly shortDescription: string | undefined;
}

Example Documenting subcommands

import { Context, Option as O } from "effect"
import type { HelpDoc } from "effect/cli"

const deploySubcommand: HelpDoc.SubcommandDoc = {
  name: "deploy",
  alias: "d",
  shortDescription: "Deploy app",
  description: "Deploy the application to the cloud"
}

const buildSubcommand: HelpDoc.SubcommandDoc = {
  name: "build",
  alias: undefined,
  shortDescription: undefined,
  description: "Build the application for production"
}

// Used in parent command's help documentation
const mainCommandHelp: HelpDoc.HelpDoc = {
  description: "Cloud deployment tool",
  usage: "myapp <command> [options]",
  annotations: Context.empty(),
  flags: [],
  subcommands: [{
    group: undefined,
    commands: [deploySubcommand, buildSubcommand]
  }]
}

mainCommandHelp.subcommands?.[0].commands.map((command) => command.name) // => ["deploy", "build"]

SubcommandGroupDoc

interface unstable

Since v4.0.0

Documentation for a grouped subcommand listing

Signature

interface SubcommandGroupDoc {
  readonly commands: readonly [SubcommandDoc, SubcommandDoc];
  readonly group: string | undefined;
}