Releases

1. 4.2.421 Jan 2025
   Release notes2 sources agree

   Bug Fixes

   • deps: bump ansis from 3.8.1 to 3.9.0 (#1298) (aefdbf8)

   Open source →
2. 4.2.314 Jan 2025
   Release notes2 sources agree

   Bug Fixes

   • deps: bump ansis from 3.6.0 to 3.8.1 (#1292) (3fdceb9)

   Open source →
3. 4.2.27 Jan 2025
   Release notes2 sources agree

   Bug Fixes

   • deps: bump ansis from 3.5.2 to 3.6.0 (15feb6e)

   Open source →
4. 4.2.16 Jan 2025
   Release notes

   Bug Fixes

   • deps: bump ansis from 3.4.0 to 3.5.2 (#1282) (bc1580b)

   Open source →
   Additional notes

   Bug Fixes

   • deps: bump ansis from 3.4.0 to 3.5.2 (#1282) (bc1580b)

   4.2.0 (2024-12-20)

   Features

   • add finally hook (16901c3)

   Open source →
5. 4.2.020 Dec 2024
   Release notes

   Features

   • add finally hook (16901c3)

   Open source →
6. 4.1.119 Dec 2024
   Release notes

   Bug Fixes

   • export action from ux (c7fad54)

   Open source →
   Additional notes

   Bug Fixes

   • export action from ux (c7fad54)

   4.1.0 (2024-12-17)

   Features

   • add atLeastOne flag property (d4746f3)

   Open source →
7. 4.1.017 Dec 2024
   Release notes

   Features

   • add atLeastOne flag property (d4746f3)

   Open source →
8. 4.0.3713 Dec 2024
   Release notes2 sources agree

   Bug Fixes

   • deps: bump nanoid from 3.3.6 to 3.3.8 (e9cbfdb)

   Open source →
9. 4.0.368 Dec 2024
   Release notes2 sources agree

   Bug Fixes

   • deps: bump lilconfig from 3.1.2 to 3.1.3 (7bdf5f3)

   Open source →
10. 4.0.358 Dec 2024
    Release notes2 sources agree

    Bug Fixes

    • deps: bump debug from 4.3.7 to 4.4.0 (e8aaaea)

    Open source →
11. 4.0.342 Dec 2024
    Release notes2 sources agree

    Bug Fixes

    • typo in ux module README (#1250) (2c44e46)

    Open source →
12. 4.0.3319 Nov 2024
    Release notes2 sources agree

    Bug Fixes

    • deps: bump cross-spawn from 7.0.3 to 7.0.6 (dfd138e)

    Open source →
13. 4.0.3212 Nov 2024
    Release notes2 sources agree

    Bug Fixes

    • add env var to disable link warning (df48c93)

    Open source →
14. 4.0.3128 Oct 2024
    Release notes2 sources agree

    Reverts

    • Revert "fix: bump is-wsl to v3 (#1211)" (#1235) (fa76792), closes #1211 #1235

    Open source →
15. 4.0.3022 Oct 2024
    Release notes2 sources agree

    Bug Fixes

    • fix aliases in config.commandIDs missing the default topic separator (#1229) (#1230) (f86d9f7)

    Open source →
16. 4.0.2915 Oct 2024
    Release notes2 sources agree

    Bug Fixes

    • improve solution for handling circular json (#1222) (9073052)

    Open source →
17. 4.0.2811 Oct 2024
    Release notes2 sources agree

    Bug Fixes

    • remove circular references when colorizing json (de9ed4e)

    Open source →
18. 4.0.273 Oct 2024
    Release notes2 sources agree

    Bug Fixes

    • add respectNoCacheDefault to help options (7320fff)

    Open source →
19. 4.0.262 Oct 2024
    Release notes2 sources agree

    Bug Fixes

    • bump is-wsl to v3 (#1211) (7fd9162)

    Open source →
20. 4.0.251 Oct 2024
    Release notes2 sources agree

    Bug Fixes

    • deprecated aliases bug (#1208) (353e715)

    Open source →
21. 4.0.241 Oct 2024
    Release notes2 sources agree

    Bug Fixes

    • use topic separator for deprecated alias warnings in help (#1209) (fb6ace2)

    Open source →
22. 4.0.2323 Sept 2024
    Release notes2 sources agree

    Bug Fixes

    • warn about node version mismatch (#1198) (ae2ceac)

    Open source →
23. 4.0.2213 Sept 2024
    Release notes2 sources agree

    Bug Fixes

    • deps: bump path-to-regexp from 6.2.1 to 6.3.0 (d051b64)

    Open source →
24. 4.0.217 Sept 2024
    Release notes2 sources agree

    Bug Fixes

    • deps: bump debug from 4.3.6 to 4.3.7 (839ab85)

    Open source →
25. 4.0.204 Sept 2024
    Release notes2 sources agree

    Bug Fixes

    • handle large throughput writes (5e336ce)

    Open source →
26. 4.0.1924 Aug 2024
    Release notes2 sources agree

    Bug Fixes

    • deps: bump micromatch from 4.0.7 to 4.0.8 (eb2aa14)

    Open source →
27. 4.0.1821 Aug 2024
    Release notes2 sources agree

    Bug Fixes

    • ts-path: use file url to import tsx at runtime (#1171) (be3f6e9)

    Open source →
28. 4.0.1728 Jul 2024
    Release notes2 sources agree

    Bug Fixes

    • deps: bump ansis from 3.3.1 to 3.3.2 (081e8bc)

    Open source →
29. 4.0.1627 Jul 2024
    Release notes2 sources agree

    Bug Fixes

    • deps: bump requirejs from 2.3.6 to 2.3.7 (216d8e7)

    Open source →
30. 4.0.1526 Jul 2024
    Release notes2 sources agree

    Bug Fixes

    • ignore escaped delimiters (#1148) (a41962a)

    Open source →
31. 4.0.1423 Jul 2024
    Release notes2 sources agree

    Bug Fixes

    • husky 9.1.1 fix (#1147) (cd3720f)

    Open source →
32. 4.0.1321 Jul 2024
    Release notes2 sources agree

    Bug Fixes

    • deps: bump ansis from 3.2.1 to 3.3.1 (a0eba0a)

    Open source →
33. 4.0.1213 Jul 2024
    Release notes2 sources agree

    Bug Fixes

    • deps: bump ansis from 3.2.0 to 3.2.1 (0d84684)

    Open source →
34. 4.0.1110 Jul 2024
    Release notes2 sources agree

    Bug Fixes

    • export ArgDefinition (#1137) (db8d951)

    Open source →
35. 4.0.1010 Jul 2024
    Release notes2 sources agree

    Bug Fixes

    • use colorize to ensure proper TTY detection (8a5d71f)

    Open source →
36. 4.0.99 Jul 2024
    Release notes2 sources agree

    Bug Fixes

    • correctly identify powershell on windows (#1134) (bcec7df)

    Open source →
37. 4.0.81 Jul 2024
    Release notes2 sources agree

    Bug Fixes

    • deps: bump minimatch from 9.0.4 to 9.0.5 (#1126) (ab337cf)

    Open source →
38. 4.0.725 Jun 2024
    Release notes2 sources agree

    Bug Fixes

    • ignore cache when reading user pjson (#1124) (6038c5c), closes #1125

    Open source →
39. 4.0.612 Jun 2024
    Release notes2 sources agree

    Bug Fixes

    • single command cli symbol on help output (#1112) (5de6a40)

    Open source →
40. 4.0.512 Jun 2024
    Release notes2 sources agree

    Bug Fixes

    • deps: bump braces from 3.0.2 to 3.0.3 (d20f082)

    Open source →
41. 4.0.411 Jun 2024
    Release notes2 sources agree

    Bug Fixes

    • use lilconfig (#1108) (804db9b)

    Open source →
42. 4.0.36 Jun 2024
    Release notes2 sources agree

    Bug Fixes

    • export parser related types (#1099) (0daafdd)

    Open source →
43. 4.0.25 Jun 2024
    Release notes2 sources agree

    Bug Fixes

    • add export for parser (#1098) (f7bfc76)

    Open source →
44. 4.0.14 Jun 2024
    Release notes

    Bug Fixes

    • parsed args regression (#1096) (53f915b)

    Open source →
    Additional notes

    Bug Fixes

    • parsed args regression (#1096) (53f915b)

    4.0.0 (2024-06-04)

    3.27.0 (2024-06-04)

    Features

    • added option to specify example flag value in docopts (#1095) (0345ac3), closes #1091

    Open source →
45. 4.0.04 Jun 2024
    Release notes

    Slimmer ux module

    As described here, we're removing most of the methods in the ux module. We're simply unable to adequately support the feature set that ux offers and think that most people would benefit from using dedicated libraries that are better supported.

    We are, however, keeping some of the functionality. The new ux module will contain the following:

    Unchanged

    • colorize
    • error
    • exit
    • action - will be unchanged from previous version except that the spinner color will be configurable using themes.
    • warn

    Renamed

    • stdout - rename of ux.log
    • stderr - rename of ux.logToStderr

    New

    • colorizeJson - Apply color theme to arbitrary JSON.

    Removed

    • annotation
    • anykey
    • confirm
    • debug
    • done (use ux.action.stop() instead)
    • flush (still available via @oclif/core/flush)
    • info (use ux.stdout instead)
    • progress
    • prompt
    • styledHeader
    • styledJSON
    • styledObject
    • table
    • trace
    • tree
    • url
    • wait

    What you'll need to do

    You will need to replace everything that ux was doing with dedicated libraries. Here are a few suggestions:

    • For prompts: inquirer
    • For progress bars: cli-progress
    • For hyperlinks: hyperlink
    • For tables: tty-table, cliui
    • For trees: object-treeify
    • For notifications: node-notifier
    • For links: terminal-link
    • For rendering react components: ink

    Theme-able spinner and JSON output

    The color of the spinner can now be customized using the spinner key in your theme.

    The JSON output can also now be customized with these keys:

    brace
    bracket
    colon
    comma
    key
    string
    number
    boolean
    null
    

    Customizable Logger

    In the current major version, we exclusively use debug for debug logs. In the next major, we're going to export a Logger interface that will allow you to provide a custom logger for @oclif/core to use. This will be useful if you want all the @oclif/core debug logs to go through your own logger.

    The default logger will continue to use debug under the hood. So if you choose to use the default, you can continue to use the DEBUG environment variable to access the debug logs in the console. The only breaking change will be that the namespace for all the logs with be prefixed with a root namespace, oclif.

    So if you're used to using DEBUG=config:* my-cli do stuff, you'll need to start doing this instead: DEBUG=oclif:config:* my-cli do stuff

    Interface

    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
    }
    

    Usage

    // 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[]) => myLogger.info(format(formatter, ...args)),
        trace: (formatter: unknown, ...args: unknown[]) => myLogger.trace(format(formatter, ...args)),
        warn: (formatter: unknown, ...args: unknown[]) => myLogger.warn(format(formatter, ...args)),
        namespace,
      };
    };
    
    export const logger = customLogger('sf');
    

    // 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,
          logger,
        },
      });
    }
    
    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({
      logger,
    });
    
    await run(process.argv.slice(2), config)
    

    Support for rc files

    Currently the configuration for oclif must live inside the oclif section of your CLI or plugin's package.json. This can be difficult if you have a large amount of configuration, you want to dynamically change the configuration, or want to ensure that your configuration is correctly typed.

    To solve this, we can now use lilconfig to read in a variety of rc files.

    Despite being able to use an rc file, @oclif/core will still be dependent on your package.json to get the name, version, and dependencies. We could ask that you put those value in your rc file, but duplicating that information across two files feels like something people would rather not do.

    If you choose to use an rc file, one thing you must consider is that there will be a slight performance hit due to needing to search for the rc file in addition to the package.json.

    This is the list of supported files. Please feel free to create a PR to add support for other files

    .oclifrc
    .oclifrc.json
    .oclifrc.js
    .oclifrc.mjs
    .oclifrc.cjs
    oclif.config.js
    oclif.config.mjs
    oclif.config.cjs
    

    Top level exports

    We'll have top level exports for:

    • args
    • command
    • config
    • errors
    • execute
    • flags
    • flush
    • handle
    • help
    • hooks
    • interfaces
    • logger
    • performance
    • run
    • settings
    • util/ids
    • ux

    The current way of accessing these looks like this:

    import {run, flush, handle} from '@oclif/core'
    

    With top level exports, you could access those like this:

    import run from '@oclif/core/run'
    import flush from '@oclif/core/flush'
    import handle from '@oclif/core/handle'
    

    The benefit of this is that you'll be able to import those utilities without also importing everything else that @oclif/core exports.

    As a result of this change, deep imports (e.g. import {Command} from '@oclif/core/lib/command.js) will no longer work.

    Bundling support for custom help classes

    In case you missed it, we introduced new command discovery strategies that make bundling possible. In order to do that, the location of commands and hooks needed to be configured using a target (i.e. a file or directory containing the commands or hooks) and an identifier (i.e. the name of the export inside the target).

    This change originally only worked for commands and hooks but now also works for custom help classes so that those can be bundled as well.

    exactOptionalPropertyTypes

    We enabled exactOptionalPropertyTypes (fixes #960) for improved type safety

    Interfaces

    Interfaces.PJSON

    Interfaces.PJSON has now been simplified to a single type instead of Interfaces.PJSON.CLI and Interfaces.PJSON.Plugin

    Interfaces.OclifConfiguration

    There's a new Interfaces.OclifConfiguration that represents everything that could be added to the oclif section of your package.json (or rc file). This is particularly helpful if you want to use a .oclifrc.ts and ensure that your oclif configuration matches the expected type.

    Runtime auto-transpilation of linked ESM plugins with tsx

    If your ESM plugin has a devDependency on tsx, then you oclif can now auto-transpile the code at runtime

    Open source →
46. 4.0.0-beta.174 Jun 2024pre-release
    Release notes

    Bug Fixes

    • isolate supports-color for testing (6f990b4)

    Open source →
47. 4.0.0-beta.164 Jun 2024pre-release
    Release notes

    4.0.0-beta.15 (2024-06-03)

    Features

    • support tsx for runtime transpilation (a194aa6)

    4.0.0-beta.14 (2024-06-03)

    Bug Fixes

    • check supports-color in colorize (ac32408)

    4.0.0-beta.13 (2024-05-24)

    Bug Fixes

    • allow empty ux.stdout (da1e4cb)

    4.0.0-beta.12 (2024-05-24)

    Bug Fixes

    • update hook type (29664ba)

    4.0.0-beta.11 (2024-05-23)

    Bug Fixes

    • improve types and ProdOnlyCache (e9c7ff7)

    4.0.0-beta.10 (2024-05-23)

    Bug Fixes

    • restore baseFlags support (#1085) (b89d73d)

    4.0.0-beta.9 (2024-05-23)

    Bug Fixes

    • clarify types (64b7669)

    Features

    • remove baseFlags (d062173)

    4.0.0-beta.8 (2024-05-20)

    Features

    • improved types and top-level exports (#1076) (3f421e7)

    4.0.0-beta.7 (2024-05-15)

    Bug Fixes

    • revert ignoreDuplicates in warn (0e99723)

    4.0.0-beta.6 (2024-05-07)

    4.0.0-beta.5 (2024-05-06)

    Features

    • support rc files (#1067) (6af9c71)

    4.0.0-beta.4 (2024-04-25)

    4.0.0-beta.3 (2024-04-24)

    Bug Fixes

    • cache child loggers (2a9164d)

    Features

    • add customizable logger (371edda)
    • remove native error logger (af986c5)

    4.0.0-beta.2 (2024-04-22)

    Features

    • slimmer ux (#1056) (879cac9)

    Open source →
48. 4.0.0-beta.153 Jun 2024pre-release
    Release notes

    Features

    • support tsx for runtime transpilation (a194aa6)

    Open source →
49. 4.0.0-beta.143 Jun 2024pre-release
    Release notes

    Bug Fixes

    • check supports-color in colorize (ac32408)

    Open source →
50. 4.0.0-beta.1324 May 2024pre-release
    Release notes

    Bug Fixes

    • allow empty ux.stdout (da1e4cb)

    Open source →
51. 4.0.0-beta.1224 May 2024pre-release
    Release notes

    Bug Fixes

    • update hook type (29664ba)

    Open source →
52. 4.0.0-beta.1123 May 2024pre-release
    Release notes

    Bug Fixes

    • improve types and ProdOnlyCache (e9c7ff7)

    Open source →
53. 4.0.0-beta.1023 May 2024pre-release
    Release notes

    Bug Fixes

    • restore baseFlags support (#1085) (b89d73d)

    Open source →
54. 4.0.0-beta.923 May 2024pre-release
    Release notes

    Bug Fixes

    • clarify types (64b7669)

    Features

    • remove baseFlags (d062173)

    Open source →
55. 4.0.0-beta.820 May 2024pre-release
    Release notes

    Features

    • improved types and top-level exports (#1076) (3f421e7)

    Open source →
56. 4.0.0-beta.715 May 2024pre-release
    Release notes

    Bug Fixes

    • revert ignoreDuplicates in warn (0e99723)

    Open source →
57. 4.0.0-beta.67 May 2024pre-release
    Release notes

    4.0.0-beta.5 (2024-05-06)

    Features

    • support rc files (#1067) (6af9c71)

    4.0.0-beta.4 (2024-04-25)

    4.0.0-beta.3 (2024-04-24)

    Bug Fixes

    • cache child loggers (2a9164d)

    Features

    • add customizable logger (371edda)
    • remove native error logger (af986c5)

    4.0.0-beta.2 (2024-04-22)

    Features

    • slimmer ux (#1056) (879cac9)

    Open source →
58. 4.0.0-beta.56 May 2024pre-release
    Release notes

    Features

    • support rc files (#1067) (6af9c71)

    Open source →
59. 4.0.0-beta.425 Apr 2024pre-release

    Nothing published for this version

60. 4.0.0-beta.324 Apr 2024pre-release
    Release notes

    Bug Fixes

    • cache child loggers (2a9164d)

    Features

    • add customizable logger (371edda)
    • remove native error logger (af986c5)

    Open source →