Console

​

Write a command

// src/commands/greet.command.ts, the class is GreetCommand
import { Argument, Command, Option, type CommandIo } from "@stackra/console";
import { Int } from "@stackra/validation";

export class GreetCommand extends Command({ name: "greet", description: "Greet someone" }) {
  /** Who to greet; asked for when missing. */
  @Argument({ optional: true })
  who?: string;

  /** Upper-case the greeting. */
  @Option({ short: "s" })
  shout = false;

  /** How many times to greet. */
  @Option({ short: "t" })
  @Int({ min: 1, max: 10 })
  times = 1;

  constructor(private readonly greetings: GreetingService) {
    super();
  }

  /** Greets, and returns the name for `--json`. */
  async handle(io: CommandIo) {
    const who =
      this.who ?? (await io.prompt.text({ message: "Who?", default: "world", option: "who" }));
    for (let i = 0; i < this.times; i++)
      io.output.success(this.shout ? `HELLO ${who.toUpperCase()}` : `Hello ${who}`);
    return { who };
  }
}

• Name. name and each alias are lower-case segments joined by -, with : between segments (tenant:seed). A bad name, a required argument after an optional one, two fields with one flag, or an option that reuses a global option is refused with ConsoleDeclarationError, before any command runs.
• Arguments bind in field order to the positional tokens. A field with no initialiser is required, unless it is @Argument({ optional: true }). The runtime cannot see a ?, so write optional: true for an optional argument with no default. A @List argument comes last and takes the rest.
• Options bind to --<kebab-name>, and to -<short> when short is given (one letter). Every option is optional. A -n, -h, -V, -v or -q is a global option and cannot be used.
• Value kind comes from @Str, @Int, @Num or @List on the field (@stackra/validation). @Int and @Num take min and max, and an out-of-range value is a usage error. A field with none of them is a boolean option or a string argument.
• Defaults are the field initialisers. A boolean option starts at its initialiser, false in the example.
• The constructor only stores collaborators. The kernel builds a throwaway instance with no arguments to read the defaults. If the constructor throws, the defaults are lost silently.
• handle(io) returns an exit code from 0 to 255, nothing (exit 0), or an object or array, which becomes the --json data. Any other return value, or a throw, exits 1.

​

Register the commands: createConsole and nodePorts

#!/usr/bin/env node
// src/main.ts
import { createConsole } from "@stackra/console";
import { nodePorts } from "@stackra/console/node";

import { GreetCommand } from "./commands/greet.command.ts";

process.exitCode = await createConsole({
  name: "acme",
  version: "1.0.0",
  commands: [GreetCommand],
}).run(process.argv.slice(2), nodePorts());

• createConsole checks the registry when it is called: a duplicate name or alias throws DuplicateCommandError, and a bad declaration throws ConsoleDeclarationError. Both name the command.
• container is an optional factory that returns an object with get(Type) and close(). It is called only to run a command, never for the list, --help or --version. The command is resolved with container.get(GreetCommand), which builds its constructor collaborators, and the container is closed after the handler returns, throws or is interrupted. Without a factory the command is built with new GreetCommand(), so a command with required collaborators needs one.
• nodePorts() from @stackra/console/node binds the run to process: its streams, its terminal state, its environment, and SIGINT and SIGTERM. run resolves with the exit code, and you assign it to process.exitCode.
• createConsole({ ... }) also takes theme, which defaults to STACKRA_THEME.

​

Output

io.output.title("Tenants");
io.output.table(
  ["Slug", "Plan"],
  [
    ["acme", "pro"],
    ["zoo", "free"],
  ],
);
await io.output.task("Seeding", () => seed());
const bar = io.output.progress(rows.length, "Importing");
bar.advance();
bar.finish();

​

Prompts and non-interactive runs

const plan = await io.prompt.select({
  message: "Which plan?",
  choices: [
    { value: "free", label: "Free" },
    { value: "pro", label: "Pro", hint: "Paid" },
  ],
  default: "free",
  option: "plan",
});
const ok = await io.prompt.confirm({ message: "Continue?", default: false, option: "yes" });

​

Exit codes

​

JSON output

acme greet Ada --json
# {"ok":true,"data":{"who":"Ada"}}
acme greet --json --times 99
# {"ok":false,"error":{"code":"usage","message":"..."}}

​

Global options

​

Colour and terminals

​

Themes

import { readFileSync } from "node:fs";

import { themeFromBrandTokens, type BrandColourTokens } from "@stackra/console";

const tokens = JSON.parse(readFileSync("brand/tokens/color.json", "utf8")) as BrandColourTokens;

export const ACME_THEME = themeFromBrandTokens(tokens, {
  name: "Acme",
  logo: ["  ___", " / _ \\", "| (_) |", " \\___/"],
  glyph: "◆",
  asciiGlyph: "*",
  gradient: ["brand-500", "brand-200"], // palette token names, placeholders here
  accent: "brand-500",
});

​

Test a command

// src/commands/__tests__/greet.command.test.ts
import { runCommandForTest } from "@stackra/console/testing";
import { describe, expect, it } from "vitest";

import { GreetCommand } from "../greet.command.ts";

describe("greet", () => {
  it("greets as JSON", async () => {
    const result = await runCommandForTest([GreetCommand], ["greet", "Ada", "--json"]);
    expect(result.exitCode).toBe(0);
    expect(result.json).toEqual({ ok: true, data: { who: "Ada" } });
  });

  it("asks the question the argument leaves out", async () => {
    const result = await runCommandForTest([GreetCommand], ["greet"], { answers: ["Grace"] });
    expect(result.asked).toEqual(["Who?"]);
    expect(result.stdout).toContain("Hello Grace");
  });
});

• The second argument is the argv after the program name. The first is a list of command classes, or a whole ConsoleConfig (the same object you pass to createConsole).
• answers are the scripted answers, in order. Giving them makes the run interactive. A text answer goes through the prompt’s validate, and a run that asks more prompts than there are answers fails naming the prompt.
• env adds environment variables. NO_COLOR=1 is set unless colour: true, so the output is plain by default. colour: true renders as a true-colour terminal would.
• columns sets the width (80 by default). container is the factory of createConsole, for fakes. signal ("SIGINT" or "SIGTERM") is sent after the command starts, to test an interruption.
• The result is { exitCode, stdout, stderr, json, asked }. json is set when all of stdout is one JSON document.

​

Scaffold a new console app

pnpm dlx @stackra/console create my-cli

• --no-install writes the files and does not install them.
• --pm pnpm|npm picks the package manager (pnpm by default).
• --tarballs <dir> installs @stackra/* from packed tarballs in that folder, for checking a release before it is published.