Goke

goke

Fetch the full README from GitHub and read it before using goke:

curl -L https://raw.githubusercontent.com/remorses/goke/main/README.md

Read the README in full every time you use goke.

>

Important: never use head or tail to truncate it. Read the full README instead.

Install

npm install goke # or bun, pnpm, etc

Quick Notes

• Core APIs: cli.option, cli.use, cli.version, cli.help, cli.completions, cli.parse
• Prefer injected { fs, console, process } over globals
• Use relative paths with injected fs; if a helper needs current-cwd semantics, pass injected process.cwd into that helper
• For JustBash compatibility tests, import the existing CLI from app code instead of defining a new CLI inside the test
• Never install `picocolors`, `chalk`, `kleur`, or any color library. Use import { colors } from 'goke' instead. It's a vendored picocolors with zero extra dependencies.

The README is the source of truth for rules, examples, testing patterns, JustBash integration, and API details.

Terminal Colors

Never install a separate color library. goke vendors picocolors and exports it as colors:

import { colors } from 'goke'

console.log(colors.green('success'))
console.log(colors.red('error'))
console.log(colors.bold(colors.cyan('info')))

Available formatters: bold, dim, italic, underline, red, green, yellow, blue, magenta, cyan, gray, bgRed, bgGreen, etc. Color support is auto-detected.

Agent Detection

goke exports isAgent, agent, agentInfo, and detectAgent() from goke/src/agents.ts. Use isAgent to detect if the CLI is running inside an AI coding agent and skip interactive prompts or prefer structured output.

import { isAgent, agent } from 'goke'

if (isAgent) {
  // skip clack prompts, output YAML/JSON instead of interactive UI
}

When guarding interactive prompts, check isAgent alongside !process.stdin.isTTY:

if (isAgent || !process.stdin.isTTY) {
  console.error('Missing --env. Usage: deploy --env staging|production')
  process.exit(1)
}

Supported agents: cursor, claude, devin, replit, gemini, codex, auggie, opencode, kiro, goose, pi. Set AI_AGENT env var to override.

Shell Completions

Always add `.completions()` next to `.help()` in every CLI. This gives users Tab completion for free.

cli.help()
cli.completions()
cli.parse()

How it works

The shell calls the CLI binary on every Tab press with a hidden --get-goke-completions flag. The binary inspects registered commands and options, prints matching candidates to stdout, and exits. No static completion file to regenerate when commands change.

README section for new CLIs

Every new CLI should include a Shell Completions section in its README. Add it after the main usage docs:

````md

Shell Completions

Enable Tab completion for your shell:

mycli completions install

Restart your shell (or run autoload -Uz compinit && compinit for zsh). Then Tab works:

mycli <TAB>          # shows all commands
mycli dep<TAB>       # completes to "deploy"
mycli deploy --<TAB> # shows available options

Completions stay up-to-date automatically. To remove:

mycli completions uninstall

````

Replace mycli with the actual CLI name.

Available completions commands

.completions() registers three subcommands:

• completions install — finds a writable shell completion directory and writes the shim script
• completions uninstall — removes installed completion files
• completions script — prints the raw script to stdout (for eval or piping)

All three accept --shell zsh or --shell bash to override auto-detection.

openInBrowser is async

openInBrowser returns a Promise<void> and must be awaited. Without await, the process may exit before the browser opens. In non-TTY environments it writes the URL to stderr, keeping stdout clean for JSON parsing.

import { openInBrowser } from 'goke'

await openInBrowser('https://example.com/dashboard')

Command Naming Conventions

ALWAYS read existing commands before adding a new one. Scan the CLI for option names, verbs, and noun patterns already in use. New commands must stay consistent with what exists.

Consistent option names

Options that do the same thing across different commands must use the same name. For example, if list commands already use --limit to cap results, never introduce --max or --count for the same purpose in a new command. Grep the codebase for similar options before picking a name.

CRUD-style spaced commands

Prefer spaced subcommands that read like noun verb:

project list
project add
project remove

Pick singular or plural for the noun and stick with it across the entire CLI. If project list exists, don't add projects add.

Consistent verbs

Choose one verb per action and reuse it everywhere:

Check which verbs the CLI already uses and match them. If existing commands use add, every new "create something" command should also use add.

Prefer Optional Flags Over Required Flags

Never make a flag required when it can be optional with an interactive fallback. Required flags force users to read --help before they can run anything. Optional flags let them run the bare command and discover options progressively through prompts.

The pattern: make the flag optional, and when the user omits it, show a clack.select prompt in TTY mode or exit with a clear error in non-TTY mode.

cli
  .command('deploy', 'Deploy the app')
  .option(
    '--env [env]',
    z.enum(['staging', 'production']).optional().describe('Target environment'),
  )
  .action(async (options) => {
    let env = options.env

    if (!env) {
      if (!process.stdin.isTTY) {
        console.error('Missing --env. Usage: deploy --env staging|production')
        process.exit(1)
      }

      const choice = await clack.select({
        message: 'Which environment?',
        options: [
          { value: 'staging', label: 'Staging' },
          { value: 'production', label: 'Production', hint: 'requires approval' },
        ],
      })
      if (clack.isCancel(choice)) {
        process.exit(0)
      }
      env = choice
    }

    // env is now guaranteed to be defined
  })

This applies to every flag that has a finite set of valid values. If you can enumerate the choices, make it a select prompt. The non-TTY error message must show the exact flag name and valid values so agents and CI scripts can self-correct.

Bad — forces users to know the flag upfront:

.option('--env <env>', z.enum(['staging', 'production']).describe('Target environment'))

Good — users can just run deploy and get prompted:

.option('--env [env]', z.enum(['staging', 'production']).optional().describe('Target environment'))

For flags with free-form string values (not enums), use clack.text instead of clack.select:

if (!options.name) {
  if (!process.stdin.isTTY) {
    console.error('Missing --name. Usage: create --name "my-project"')
    process.exit(1)
  }

  const name = await clack.text({ message: 'Project name' })
  if (clack.isCancel(name)) process.exit(0)
  options.name = name
}

Interactive Prompts with @clack/prompts

Use @clack/prompts for interactive CLI prompts like select, confirm, and text input.

npm install @clack/prompts

import * as clack from '@clack/prompts'

const method = await clack.select({
  message: 'Choose authentication method',
  options: [
    { value: 'google', label: 'Google', hint: 'opens browser for OAuth' },
    { value: 'imap', label: 'Other', hint: 'IMAP/SMTP with password' },
  ],
})
if (clack.isCancel(method)) {
  process.exit(0)
}

const confirmed = await clack.confirm({
  message: 'Delete this item?',
  initialValue: false,
})
if (clack.isCancel(confirmed) || !confirmed) {
  process.exit(0)
}

Always guard clack prompts with process.stdin.isTTY. Agents and CI often run with non-TTY stdin, so interactive prompts must fall back to explicit CLI options instead of hanging.

Select prompts

When a command shows a select prompt in TTY mode, always add a matching CLI option so agents can pass the choice directly.

cli
  .command('login', 'Authenticate')
  .option(
    '--method <method>',
    z.enum(['google', 'imap']).optional().describe('Authentication method'),
  )
  .action(async (options) => {
    let method = options.method

    if (!method) {
      if (!process.stdin.isTTY) {
        console.error('Run non-interactively with: zele login --method google|imap')
        process.exit(1)
      }

      const choice = await clack.select({
        message: 'Choose authentication method',
        options: [
          { value: 'google', label: 'Google', hint: 'opens browser for OAuth' },
          { value: 'imap', label: 'Other', hint: 'IMAP/SMTP with password' },
        ],
      })
      if (clack.isCancel(choice)) {
        process.exit(0)
      }
      method = choice
    }

    if (method === 'imap') {
      return
    }
  })

Confirm prompts

For destructive confirmations, add a --force flag and exit with a clear error in non-TTY mode when it is missing.

cli
  .command('delete <id>', 'Delete an item')
  .option('--force', 'Skip confirmation')
  .action(async (id, options) => {
    if (!options.force) {
      if (!process.stdin.isTTY) {
        console.error('Use --force to delete non-interactively')
        process.exit(1)
      }

      const confirmed = await clack.confirm({
        message: `Delete ${id}?`,
        initialValue: false,
      })
      if (clack.isCancel(confirmed) || !confirmed) {
        return
      }
    }
  })