#Context

The central API surface threaded through every handler and middleware. Provides typed access to args, config, log, format, store, error handling, and CLI metadata.

#Properties

#ctx.args

Deeply readonly parsed args for the matched command. The type is a merge of MalttyArgs (global augmentation) and the command's own args definition.

const deploy = command({
  options: z.object({
    env: z.enum(['staging', 'production']).describe('Target environment'),
  }),
  async handler(ctx) {
    ctx.args.env // 'staging' | 'production'
  },
})

#ctx.config

A ConfigHandle decorated by the config() middleware from maltty/config. Only present when the config middleware is registered. Config loads lazily by default -- call ctx.config.load() to read and validate the config file, which returns a Result tuple.

Use ConfigType with module augmentation on maltty/config to derive ConfigRegistry from your Zod schema:

// src/config.ts
import type { ConfigType } from 'maltty/config'
import { z } from 'zod'

export const configSchema = z.object({
  apiUrl: z.string().url(),
  org: z.string().min(1),
})

declare module 'maltty/config' {
  interface ConfigRegistry extends ConfigType<typeof configSchema> {}
}

Then register the config middleware:

import { cli } from 'maltty'
import { config } from 'maltty/config'
import { configSchema } from './config.js'

cli({
  name: 'my-app',
  version: '1.0.0',
  middleware: [config({ schema: configSchema })],
  commands: import.meta.dirname + '/commands',
})

Commands load and access config via the handle:

export default command({
  async handler(ctx) {
    const [error, result] = await ctx.config.load()
    if (error) {
      ctx.fail(error.message)
      return
    }
    result.config.apiUrl // string
    result.config.org // string
  },
})

Pass { layers: true } to load() to include layer metadata:

const [error, result] = await ctx.config.load({ layers: true })
result.config.apiUrl // string
result.layers // ConfigLayer[]

Run maltty add config to scaffold this setup in an existing project, or pass --config to maltty init when creating a new project.

#ctx.log

Structured logging API on the base context. All logging methods write to stderr.

ctx.log.intro('my-app v1.0.0')
ctx.log.info('Starting deployment...')
ctx.log.success('Deployed successfully')
ctx.log.outro('Done')

#ctx.prompts

Interactive prompts that suspend execution until the user provides input. Cancellation (Ctrl-C) throws a ContextError with code PROMPT_CANCELLED.

const env = await ctx.prompts.select({
  message: 'Target environment',
  options: [
    { label: 'Staging', value: 'staging' },
    { label: 'Production', value: 'production' },
  ],
})

#ctx.status.spinner

Manage a spinner for long-running operations.

ctx.status.spinner.start('Bundling...')
ctx.status.spinner.message('Compiling binaries...')
ctx.status.spinner.stop('Build complete')

#ctx.colors

Color formatting utilities powered by picocolors. Use for coloring summary values, diagnostic output, and other terminal text.

const c = ctx.colors
ctx.log.info(`Status: ${c.green('passing')}`)

Available formatters: bold, dim, italic, underline, red, green, yellow, blue, magenta, cyan, white, gray, and more.

#ctx.format

Pure string formatters for data serialization. These return strings and perform no I/O -- write the result to stdout yourself.

// JSON output
process.stdout.write(ctx.format.json({ name: 'deploy', status: 'success' }))

// Table output
process.stdout.write(
  ctx.format.table([
    { name: 'deploy', status: 'success' },
    { name: 'migrate', status: 'skipped' },
  ])
)

#ctx.store

Typed in-memory key-value store for passing data between middleware and handlers. This is the recommended way to communicate state through the middleware chain.

const loadUser = middleware(async (ctx, next) => {
  ctx.store.set('user', await fetchUser())
  await next()
})

const deploy = command({
  middleware: [loadUser],
  async handler(ctx) {
    const user = ctx.store.get('user')
  },
})

#ctx.fail()

Throws a ContextError with a clean user-facing message. No stack trace is shown in production. The process exits with the specified exit code.

ctx.fail('Deployment failed')
ctx.fail('Invalid token', { code: 'AUTH_ERROR', exitCode: 2 })

#ctx.meta

Deeply readonly CLI metadata.

dirs contains local (resolved relative to the project root) and global (resolved relative to ~). Both default to .<cli-name>.

#ctx.auth

Auth context decorated by the auth() middleware from maltty/auth. Only present when the auth middleware is registered.

if (!ctx.auth.credential()) {
  ctx.fail('Not authenticated. Run `my-app login` first.')
}

const [error, credential] = await ctx.auth.login()
if (error) {
  ctx.fail(error.message)
}

See Authentication for the full auth system reference.

#Module Augmentation

maltty exposes empty interfaces that consumers extend via TypeScript declaration merging. This adds project-wide type safety without threading generics through every handler.

For ConfigRegistry, use the ConfigType utility to derive the type from your Zod schema (see ctx.config above). Note that config augmentation targets maltty/config, while other interfaces target maltty:

declare module 'maltty' {
  interface MalttyArgs {
    verbose: boolean
  }

  interface MalttyStore {
    token: string
  }
}

// Config augmentation uses a separate module
declare module 'maltty/config' {
  interface ConfigRegistry extends ConfigType<typeof configSchema> {}
}

#Context in screen commands

Screen commands defined with screen() do not receive a CommandContext object. Instead, parsed args are passed directly as props to the React component, and runtime values are accessed via hooks:

See Screens for details.

#References

• Core Reference
• Lifecycle
• Configuration
• Authentication