HelpDoc

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 Added in v4.0.0 Source

Models

ArgDoc interface

Added in v4.0.0 Source

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/unstable/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

Added in v4.0.0 Source

Documentation for a command usage example

Signature

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

FlagDoc interface

Added in v4.0.0 Source

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/unstable/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

Added in v4.0.0 Source

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/unstable/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

Added in v4.0.0 Source

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/unstable/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

Added in v4.0.0 Source

Documentation for a grouped subcommand listing

Signature

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