Codama ➤ CLI

This package provides a CLI for the Codama library that can be used to run scripts on Codama IDLs.

Note that, whilst the CLI code is located in the @codama/cli package, the CLI binary is directly provided by the main codama library.

Getting started

To get started with Codama, simply install codama to your project and run the init command like so:

pnpm install codama
codama init

You will be prompted for the path of your IDL and asked to select any script presets you would like to use.

codama run

Once you have your codama config file, you can run your Codama scripts using the codama run command as follows:

codama run         # Only runs your before visitors.
codama run js rust # Runs your before visitors followed by the `js` and `rust` scripts.
codama run --all   # Runs your before visitors followed by all your scripts.

The configuration file

The codama config file defines an object containing the following fields:

• idl (string): The path to the IDL file. This can be a Codama IDL or an Anchor IDL which will be automatically converted to a Codama IDL.
• before (array): An array of visitors that will run before every script.
• scripts (object): An object defining the available Codama scripts. The keys identify the scripts and the values are arrays of visitors that make up the script.

Whether it is in the before array or in the scripts values, when defining a visitor you may either provide:

• an object with the following fields:
  • from (string): The import path to the visitor.
  • args (array): An array of arguments to pass to the visitor.
• a string: The import path to the visitor. This is equivalent to providing an object with a from field and an empty args array.

Visitor import paths can either be local paths (pointing to JavaScript files exporting visitors) or npm package names. By default, the default export will be used but you may specify a named export by appending a # followed by the export name. When resolved, the imported element inside the module should either be a Visitor<any, 'rootNode'> or a function that returns a Visitor<any, 'rootNode'> given the arguments provided. Here are some examples of valid visitor import paths:

'./my-visitor.js'; // Relative local path to a visitor module.
'/Users/me/my-visitor.js'; // Absolute local path to a visitor module.
'some-library'; // npm package name.
'@acme/some-library'; // Scoped npm package name.
'./my-visitor.js#myExport'; // Named export from a local path.
'@acme/some-library#myExport'; // Named export from an npm package.

Here is an example of what a Codama configuration file might look like:

{
    "idl": "path/to/idl",
    "before": [
        "./my-before-visitor.js",
        { "from": "some-library#removeTypes", "args": [["internalFoo", "internalBar"]] }
    ],
    "scripts": {
        "js": [
            {
                "from": "@codama/renderers-js",
                "args": ["clients/js/src/generated"]
            }
        ]
    }
}

Note that you can use the --js flag to generate a .js configuration file when running the init command.