Commands

Commands are the building blocks of your CLI. Place files in src/cli/ and each file becomes a command. The file path determines the command name.

File-based routing

File	Command
`hello.ts`	`mycli hello`
`db/migrate.ts`	`mycli db migrate`
`config/set.ts`	`mycli config set`

hello.tsmycli hello

greet.tsmycli greet

migrate.tsmycli db migrate

seed.tsmycli db seed

get.tsmycli config get

set.tsmycli config set

Basic command

Every command file must export a default function. This is the handler that runs when the command is invoked.

src/cli/greet.ts

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

export const config = {
  description: 'Greet the user'
}

export default (ctx: CliContext) => {
  console.log('Hello!')
}

src/cli/greet.js

export const config = {
  description: 'Greet the user'
}

export default (ctx) => {
  console.log('Hello!')
}

Handler context

The handler receives a CliContext object with the following properties:

Property	Type	Description
`args`	`string[]`	Positional arguments passed after the command
`options`	`object`	Parsed option values (typed when using `createCliCommandConfig`)
`logger`	`Logger`	Robo.js logger instance
`cwd`	`string`	Current working directory
`argv`	`string[]`	Raw arguments after the command name

Command with options

Add typed options using createCliCommandConfig with as const for full TypeScript inference.

src/cli/build.ts

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

export const config = createCliCommandConfig({
  description: 'Build the project',
  options: [
    { alias: '-w', name: '--watch', description: 'Watch for changes', type: 'boolean' },
    { alias: '-o', name: '--output', description: 'Output directory', type: 'string', default: './build' }
  ]
} as const)

export default (ctx: CliContext<typeof config>) => {
  console.log(`Building to ${ctx.options.output}...`)
  if (ctx.options.watch) {
    console.log('Watching for changes...')
  }
}

src/cli/build.js

export const config = {
  description: 'Build the project',
  options: [
    { alias: '-w', name: '--watch', description: 'Watch for changes', type: 'boolean' },
    { alias: '-o', name: '--output', description: 'Output directory', type: 'string', default: './build' }
  ]
}

export default (ctx) => {
  console.log(`Building to ${ctx.options.output}...`)
  if (ctx.options.watch) {
    console.log('Watching for changes...')
  }
}

Async commands

Handlers can be async. The CLI waits for the promise to resolve before exiting.

src/cli/deploy.ts

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

export const config = createCliCommandConfig({
  description: 'Deploy the project',
  options: [
    { alias: '-e', name: '--env', description: 'Target environment', type: 'string', default: 'production' }
  ]
} as const)

export default async (ctx: CliContext<typeof config>) => {
  console.log(`Deploying to ${ctx.options.env}...`)
  // Your deploy logic here
  console.log('Done!')
}

src/cli/deploy.js

export const config = {
  description: 'Deploy the project',
  options: [
    { alias: '-e', name: '--env', description: 'Target environment', type: 'string', default: 'production' }
  ]
}

export default async (ctx) => {
  console.log(`Deploying to ${ctx.options.env}...`)
  // Your deploy logic here
  console.log('Done!')
}

Commands

Commands

File-based routing

Basic command

Handler context

Command with options

Async commands

Next steps

Options

Subcommands

On this page