Options

Options let users pass flags and values to your commands. Use createCliCommandConfig with as const for full TypeScript inference on option types.

Defining options

Each option in the options array describes a flag your command accepts.

src/cli/serve.ts

import { createCliCommandConfig, type CliContext } from 'robo.js/cli.js'

export const config = createCliCommandConfig({
  description: 'Start a development server',
  options: [
    { alias: '-p', name: '--port', description: 'Port number', type: 'number', default: 3000 },
    { alias: '-H', name: '--host', description: 'Host address', type: 'string' },
    { alias: '-o', name: '--open', description: 'Open in browser', type: 'boolean' }
  ]
} as const)

export default (ctx: CliContext<typeof config>) => {
  console.log(`Starting server on ${ctx.options.host ?? 'localhost'}:${ctx.options.port}`)
  if (ctx.options.open) {
    console.log('Opening browser...')
  }
}

src/cli/serve.js

export const config = {
  description: 'Start a development server',
  options: [
    { alias: '-p', name: '--port', description: 'Port number', type: 'number', default: 3000 },
    { alias: '-H', name: '--host', description: 'Host address', type: 'string' },
    { alias: '-o', name: '--open', description: 'Open in browser', type: 'boolean' }
  ]
}

export default (ctx) => {
  console.log(`Starting server on ${ctx.options.host ?? 'localhost'}:${ctx.options.port}`)
  if (ctx.options.open) {
    console.log('Opening browser...')
  }
}

Option properties

Prop

Type

Type inference

When using createCliCommandConfig with as const, TypeScript automatically infers the correct types for each option based on its type, required, and default fields.

src/cli/example.ts

import { createCliCommandConfig, type CliContext } from 'robo.js/cli.js'

export const config = createCliCommandConfig({
  description: 'Type inference example',
  options: [
    { alias: '-p', name: '--port', type: 'number', default: 3000 },     // number (has default)
    { alias: '-h', name: '--host', type: 'string' },                     // string | undefined
    { alias: '-v', name: '--verbose', type: 'boolean', required: true }  // boolean (required)
  ]
} as const)

export default (ctx: CliContext<typeof config>) => {
  ctx.options.port    // TypeScript knows: number
  ctx.options.host    // TypeScript knows: string | undefined
  ctx.options.verbose // TypeScript knows: boolean
}

The as const assertion is required for type inference to work. Without it, TypeScript widens option types to string instead of inferring specific types.

Positional arguments

Enable positionalArgs to accept values without flags. Positional arguments are available via ctx.args.

src/cli/install.ts

import { createCliCommandConfig, type CliContext } from 'robo.js/cli.js'

export const config = createCliCommandConfig({
  description: 'Install packages',
  positionalArgs: true
} as const)

export default (ctx: CliContext<typeof config>) => {
  const packages = ctx.args
  console.log(`Installing: ${packages.join(', ')}`)
}

src/cli/install.js

export const config = {
  description: 'Install packages',
  positionalArgs: true
}

export default (ctx) => {
  const packages = ctx.args
  console.log(`Installing: ${packages.join(', ')}`)
}

mycli install lodash express react
# Installing: lodash, express, react

Combining options and positional args

Options and positional arguments work together. Named flags are parsed as options, and remaining values become positional args.

src/cli/add.ts

import { createCliCommandConfig, type CliContext } from 'robo.js/cli.js'

export const config = createCliCommandConfig({
  description: 'Add items to the project',
  positionalArgs: true,
  options: [
    { alias: '-D', name: '--dev', description: 'Add as dev dependency', type: 'boolean' }
  ]
} as const)

export default (ctx: CliContext<typeof config>) => {
  const items = ctx.args
  const prefix = ctx.options.dev ? '(dev) ' : ''
  items.forEach((item) => console.log(`${prefix}Adding ${item}`))
}

src/cli/add.js

export const config = {
  description: 'Add items to the project',
  positionalArgs: true,
  options: [
    { alias: '-D', name: '--dev', description: 'Add as dev dependency', type: 'boolean' }
  ]
}

export default (ctx) => {
  const items = ctx.args
  const prefix = ctx.options.dev ? '(dev) ' : ''
  items.forEach((item) => console.log(`${prefix}Adding ${item}`))
}

mycli add react vue --dev
# (dev) Adding react
# (dev) Adding vue

Options

Options

Defining options

Option properties

Type inference

Positional arguments

Combining options and positional args

Next steps

Commands

Subcommands

On this page