Command

The @talosjs/command component is a small CLI command framework. Each command implements the ICommand interface (getName, getDescription, and run) and registers itself with @decorator.command(). The run() entry point parses Bun.argv, resolves the matching command from the container by name, and executes it with fully typed options. Commands are resolved through @talosjs/container, so they support dependency injection and the full range of scopes.

What it gives you

@decorator.command() registers a class with the DI container and the global command registry in one step. The generic ICommand<Options> interface carries your option type through run(), and run() itself parses named options, booleans, and positionals from Bun.argv before forwarding them to the command. Because commands resolve through @talosjs/container, they work with the Singleton, Request, and Transient scopes. Failures throw a CommandException that carries a machine-readable key, a message, and a data object, and it is logged automatically. For scaffolding, commandCreate writes a command class, its test stub, and a barrel export from the bundled templates.

How it works

You implement ICommand, register it with @decorator.command(), then import the file so the decorator runs before you call run(). The entry point reads the command name from the third positional argument, looks it up by getName(), and invokes run() with the parsed options.

Member	Purpose
`getName()`	Returns the command name used to match CLI input (e.g. `db:seed`).
`getDescription()`	Returns a human-readable description of the command.
`run(options)`	Executes the command with the parsed options.

The runtime pieces fit together as follows:

Export	Role
`decorator.command(scope?)`	Registers a command class with the container and `COMMANDS_CONTAINER`.
`run()`	Parses `Bun.argv`, resolves the command by name, and runs it.
`getCommand(name)`	Resolves a single registered command by name, or `null`.
`commandCreate(config)`	Scaffolds a command file and test file from templates.
`COMMANDS_CONTAINER`	Global array of every registered command constructor.

When no command matches the requested name, or the command throws, run() logs the error via TerminalLogger and exits with code 1.

Decorator and usage

`@decorator.command()`

Registers a command class with the container and pushes it onto the global COMMANDS_CONTAINER. It accepts an optional EContainerScope (defaults to Singleton). Implement ICommand and register the class:

import { decorator } from "@talosjs/command";
import type { ICommand } from "@talosjs/command";

interface GreetOptions {
  name?: string;
}

@decorator.command()
class GreetCommand implements ICommand<GreetOptions> {
  public getName(): string {
    return "greet";
  }

  public getDescription(): string {
    return "Greet a user by name";
  }

  public async run(options: GreetOptions): Promise<void> {
    const who = options.name ?? "World";
    console.log(`Hello, ${who}!`);
  }
}

Pass a scope when you need a fresh instance per resolution:

import { decorator } from "@talosjs/command";
import { EContainerScope } from "@talosjs/container";

@decorator.command(EContainerScope.Transient)
class BuildCommand implements ICommand {
  // ...
}

Running the entry point

Call run() in your CLI entry file. Import the files that register commands first so their decorators execute:

import { run } from "@talosjs/command";
import "./commands"; // imports files that register commands via @decorator.command()

await run();

Invoke it from the terminal, where the command name is the third positional argument:

bun run cli.ts greet --name Alice
# Hello, Alice!

Resolving a command manually

getCommand() returns a registered command by name, or null when none matches:

import { getCommand } from "@talosjs/command";

const command = getCommand("greet");

if (command) {
  await command.run({ name: "Bob" });
}

Injecting dependencies

Because commands resolve through @talosjs/container, you can inject services in the constructor:

import { decorator } from "@talosjs/command";
import { inject } from "@talosjs/container";

@decorator.command()
class MigrateCommand implements ICommand {
  constructor(@inject(MigrationService) private readonly migrations: MigrationService) {}

  public getName(): string {
    return "db:migrate";
  }

  public getDescription(): string {
    return "Run database migrations";
  }

  public async run(options: { drop?: boolean }): Promise<void> {
    await this.migrations.run({ drop: options.drop });
  }
}

Exceptions

The component throws CommandException for command-related errors. It extends Exception from @talosjs/exception, carries a machine-readable key, a human-readable message, and a data object, and reports an InternalServerError HTTP status. You supply the key at throw time, so choose a stable, descriptive value per failure.

new CommandException(message: string, key: string, data?: Record<string, unknown>)

Throw it from run() with a stable key and contextual data:

import { CommandException } from "@talosjs/command";

@decorator.command()
class ValidateCommand implements ICommand {
  public getName(): string {
    return "validate";
  }

  public getDescription(): string {
    return "Validate project configuration";
  }

  public async run(options: { name?: string }): Promise<void> {
    if (!options.name) {
      throw new CommandException("The --name option is required", "MISSING_NAME", {
        received: options,
      });
    }
  }
}

Catch it to inspect the structured fields:

import { CommandException } from "@talosjs/command";

try {
  await command.run(options);
} catch (error) {
  if (error instanceof CommandException) {
    logger.error(`Command error [${error.key}]: ${error.message}`, error.data);
  } else {
    throw error;
  }
}

When run() catches an exception it logs it via TerminalLogger and exits with code 1, so uncaught CommandExceptions surface automatically.

Guidance

Name commands namespace:action, with a colon-separated scheme like db:migrate or user:import, so related commands group naturally. Type your options by passing an options type to ICommand<Options> and defining every flag it takes, rather than leaning on Record<string, unknown>. Decorators only register a command when its module is loaded, so keep a barrel file and import it before you call run(). Resolve services through the container constructor instead of constructing them, which keeps commands testable. When you throw CommandException, keep the key constant per failure and put the variable detail in data. A good run() validates its options up front, fails fast with a clear exception, and then does the work. Default to Singleton scope; reach for Transient only when a command must not share state across resolutions.

CLI command

Scaffold a command class and its test file with the generator. It writes the class under modules/<module>/src/commands/<Name>Command.ts, a test under modules/<module>/tests/commands/<Name>Command.spec.ts, updates the commands.ts barrel export, and creates bin/command/run.ts for the module if it is missing.

# Interactive: prompts for the name
talos command:create

# Provide the name
talos command:create --name=ImportUser

# Target a module and overwrite
talos command:create --name=ImportUser --module=auth --override

Option	Description	Default
`--name`	Command class name. Pass any casing; it is normalized to PascalCase and the `Command` suffix is appended automatically.	Prompted if omitted
`--module`	Target module the class is generated into.	`shared`
`--override`	Overwrite an existing class without prompting.	`false`

The generated class is a registered ICommand stub, ready for you to define its options and implement run():

import { type ICommand, decorator } from "@talosjs/command";

type CommandOptionsType = {
  name?: string;
};

@decorator.command()
export class ImportUserCommand<T extends CommandOptionsType = CommandOptionsType> implements ICommand<T> {
  public getName(): string {
    return "import:user";
  }

  public getDescription(): string {
    return "Execute import:user command";
  }

  public async run(options: T): Promise<void> {
    // TODO: Implement command logic
  }
}

Run a generated command from its module by its getName() value — extra arguments are forwarded to the command:

talos command:run import:user --name=fixtures

command:run scans every module under modules/ for a bin/command/run.ts, locates the command whose getName() matches, and spawns it. It exits with code 1 when the command is not found in any module or when it fails. See command:create and command:run for the full command references.

Use with Claude and Codex

The generator ships a matching command:create skill. It runs the scaffold and then guides your AI agent through completing the command: defining the options type and implementing run(). Initialize the skills once for your agent:

Claude
Codex

talos agent:skills:create

Then ask Claude in natural language. It maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a command that imports users from a CSV file.

talos agent:skills:create

Then ask Codex the same way; it maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a command that imports users from a CSV file.

For example, the prompt above maps to command:create --name=ImportUser, then implements the run() method to read the CSV and persist the users.

Getting Started

AI

Framework

Command Line

What it gives you

How it works

Decorator and usage

`@decorator.command()`

Running the entry point

Resolving a command manually

Injecting dependencies

Exceptions

Guidance

CLI command

Use with Claude and Codex

​What it gives you

​How it works

​Decorator and usage

​@decorator.command()

​Running the entry point

​Resolving a command manually

​Injecting dependencies

​Exceptions

​Guidance

​CLI command

​Use with Claude and Codex

What it gives you

How it works

Decorator and usage

`@decorator.command()`

Running the entry point

Resolving a command manually

Injecting dependencies

Exceptions

Guidance

CLI command

Use with Claude and Codex