Skip to main content


By default oclif uses debug to generate debug logs that can be viewed using the DEBUG environment variable. To see all the logs, you can set DEBUG=oclif*.

You can also provide oclif with a custom logger, if you prefer for oclif's logs to be sent to that instead of debug.

This is the interface that your logger must match:

export type Logger = {
debug: (formatter: unknown, ...args: unknown[]) => void
error: (formatter: unknown, ...args: unknown[]) => void
info: (formatter: unknown, ...args: unknown[]) => void
trace: (formatter: unknown, ...args: unknown[]) => void
warn: (formatter: unknown, ...args: unknown[]) => void
child: (namespace: string) => Logger
namespace: string

And here's an example:

// oclif-logger.ts
import { format } from 'node:util';
import { Interfaces } from '@oclif/core';
import { Logger } from './my-cli-logger';

export const customLogger = (namespace: string): Interfaces.Logger => {
const myLogger = new Logger(namespace);
return {
child: (ns: string, delimiter?: string) => customLogger(`${namespace}${delimiter ?? ':'}${ns}`),
debug: (formatter: unknown, ...args: unknown[]) => myLogger.debug(format(formatter, ...args)),
error: (formatter: unknown, ...args: unknown[]) => myLogger.error(format(formatter, ...args)),
info: (formatter: unknown, ...args: unknown[]) =>, ...args)),
trace: (formatter: unknown, ...args: unknown[]) => myLogger.trace(format(formatter, ...args)),
warn: (formatter: unknown, ...args: unknown[]) => myLogger.warn(format(formatter, ...args)),

export const logger = customLogger('my-cli');

You now need to provide this logger to oclif so that it can use it:

// bin/run.js
#!/usr/bin/env node

async function main() {
const {execute} = await import('@oclif/core');
const { logger } = await import('../dist/oclif-logger.js');
await oclif.execute({
dir: import.meta.url,
loadOptions: {
root: import.meta.dirname,

await main();

You can also provide the logger to Config, in the event that you instantiate Config before calling run or execute

import {Config, run} from '@oclif/core'
const config = await config.load({

await run(process.argv.slice(2), config)