cligentic block

global-flags

Standard global flags for agent-first CLIs: --json, --dry-run, --profile, --no-input, --quiet, --verbose. Normalizes raw argv into typed GlobalFlags. Includes flag definitions for any parser.

Install

global-flags demo

NPM dependencies

zero deps — pure TS

Block dependencies

standalone

Size

66 LOC

What it does

Defines the six global flags every agent-first CLI should expose. Normalizes raw argv output from any parser (commander, citty, yargs) into a typed GlobalFlags object that other blocks consume.

The six flags

Flag	Default	Purpose
`--json`	auto (piped = true)	Emit JSON for agents
`--dry-run`	false	Validate without calling upstream
`--profile <name>`	none	Config profile to use
`--no-input`	auto (CI = true)	Never prompt, fail fast
`-q, --quiet`	false	Suppress non-essential output
`-v, --verbose`	false	Verbose logging to stderr

Quickstart

import { parseGlobalFlags, getGlobalFlagDefs } from "@/cli/foundation/global-flags";
 
// Register flags with your parser
for (const f of getGlobalFlagDefs()) {
  program.option(f.flag, f.description);
}
 
// In a command handler
program.command("list").action(async (rawOpts) => {
  const flags = parseGlobalFlags(rawOpts);
 
  // Pass to other blocks
  emit(data, flags);           // json-mode reads flags.json
  note("loading...", flags);   // respects flags.quiet
  loadConfig(dir, flags.profile);  // config reads flags.profile
});

Why these six

--json and --quiet are consumed by json-mode
--profile is consumed by config
--dry-run is consumed by any write operation (safety guard)
--no-input prevents prompts in CI and agent mode
--verbose enables debug output on stderr

Every flag has an env var fallback (CLI_JSON, CI, CLI_PROFILE) so agents can set behavior via environment without flag parsing.

Source

The full file, 66 lines.

This is the exact TypeScript that lands in your project when you run the install command. Read it, copy it, edit it, own it. cligentic never touches it again.

src/cli/foundation/global-flags.ts

// cligentic block: global-flags
//
// Standard global flags every agent-first CLI should expose.
// Returns a typed options object that other blocks (json-mode,
// killswitch, config) consume.
//
// Usage:
//   import { type GlobalFlags, parseGlobalFlags } from "./foundation/global-flags";
//
//   // After your argv parser extracts raw opts:
//   const flags = parseGlobalFlags(rawOpts);
//   emit(data, flags);  // json-mode reads flags.json
//   note("loading...", flags);  // respects flags.quiet

export type GlobalFlags = {
  /** Emit JSON output for agents. Implied when stdout is piped. */
  json: boolean;
  /** Validate without calling upstream. */
  dryRun: boolean;
  /** Config profile name. */
  profile: string | undefined;
  /** Never prompt, fail fast. For CI and agents. */
  noInput: boolean;
  /** Suppress non-essential output. */
  quiet: boolean;
  /** Verbose logging to stderr. */
  verbose: boolean;
};

/**
 * Normalizes raw CLI options into a typed GlobalFlags object.
 * Handles common aliases and env var fallbacks.
 *
 * Pass the output of your argv parser (commander opts, citty args, etc).
 */
export function parseGlobalFlags(raw: Record<string, unknown> = {}): GlobalFlags {
  return {
    json: Boolean(raw.json ?? process.env.CLI_JSON === "1"),
    dryRun: Boolean(raw.dryRun ?? raw["dry-run"] ?? false),
    profile: (raw.profile as string) ?? process.env.CLI_PROFILE ?? undefined,
    noInput: Boolean(raw.noInput ?? raw["no-input"] ?? process.env.CI === "true"),
    quiet: Boolean(raw.quiet ?? raw.q ?? false),
    verbose: Boolean(raw.verbose ?? raw.v ?? false),
  };
}

/**
 * Returns the flag definitions as an array. Useful for registering
 * with commander, citty, or any argv parser.
 *
 * Example with commander:
 *   for (const f of getGlobalFlagDefs()) {
 *     program.option(f.flag, f.description);
 *   }
 */
export function getGlobalFlagDefs() {
  return [
    { flag: "--json", description: "Emit JSON output for agents" },
    { flag: "--dry-run", description: "Validate without calling upstream" },
    { flag: "--profile <name>", description: "Config profile to use" },
    { flag: "--no-input", description: "Never prompt, fail fast" },
    { flag: "-q, --quiet", description: "Suppress non-essential output" },
    { flag: "-v, --verbose", description: "Verbose logging to stderr" },
  ] as const;
}