Skip to content

Commit c9e3aa1

Browse files
lorisleivalorisleiva
authored
Update CLI documentation (#858)
1 parent bfcf9d6 commit c9e3aa1

File tree

1 file changed

+192
-40
lines changed

1 file changed

+192
-40
lines changed

‎packages/cli/README.md‎

Lines changed: 192 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -11,77 +11,229 @@ This package provides a CLI for the Codama library that can be used to run scrip
1111

1212
Note that, whilst the CLI code is located in the `@codama/cli` package, the CLI binary is also included in the main `codama` library.
1313

14-
## Getting started
14+
## Installation
1515

16-
To get started with Codama, simply install `codama` to your project and run the `init` command like so:
16+
Once you have the `codama` package installed, you can use the CLI using the `codama` binary.
1717

1818
```sh
1919
pnpm install codama
20-
pnpm codama init
20+
codama --help
2121
```
2222

23-
You will be prompted for the path of your IDL and asked to select any script presets you would like to use.
23+
Note that you may install it from `@codama/cli` instead if you only want the CLI without the rest of the Codama library.
24+
25+
## Commands
26+
27+
### `codama init`
2428

25-
To initialize a [gill based Codama](https://gill.site/docs/guides/codama) configuration file, run the `init` command with the `--gill` flag like so:
29+
To get started with the Codama CLI, you will first need to create a [Codama configuration file](#configuration-file). You can do this using the `init` command as follows:
2630

2731
```sh
28-
pnpm codama init --gill
32+
codama init
2933
```
3034

31-
## `codama run`
35+
You will be prompted for the path of your IDL and asked to select any script presets you would like to use.
36+
37+
Here are the available options for the `init` command:
3238

33-
Once you have your codama configuration file, you can run your Codama scripts using the `codama run` command as follows:
39+
| Option | Description |
40+
| ----------------- | --------------------------------------------------------------------------------------------------------- |
41+
| `[output]` | As an optional argument, you may provide the path used to output the configuration file. |
42+
| `--default`, `-d` | Skips all prompts and uses the default values. |
43+
| `--force` | Overwrites any existing configuration file. |
44+
| `--gill` | Initializes a configuration file for a [gill based Codama](https://gill.site/docs/guides/codama) project. |
45+
| `--js` | Generates a JavaScript configuration file instead of a JSON one. |
46+
47+
### `codama run`
48+
49+
Once you have a configuration file, you can run your Codama scripts using the `codama run` command as follows:
3450

3551
```sh
36-
pnpm codama run # Only runs your before visitors.
37-
pnpm codama run js rust # Runs your before visitors followed by the `js` and `rust` scripts.
38-
pnpm codama run --all # Runs your before visitors followed by all your scripts.
52+
codama run # Only runs your before visitors, no scripts.
53+
codama run js rust # Runs your before visitors followed by the `js` and `rust` scripts.
54+
codama run --all # Runs your before visitors followed by all your scripts.
3955
```
4056

41-
## The configuration file
57+
Here are the available options for the `run` command:
58+
59+
| Option | Description |
60+
| ----------------------- | ---------------------------------------------------------------------------------------- |
61+
| `[scripts...]` | As optional arguments, you may provide the names of the scripts you wish to run. |
62+
| `--all`, `-a` | Runs all the scripts defined in your configuration file. |
63+
| `--config <path>`, `-c` | Specifies the path to your configuration file. Defaults to `codama.json` or `codama.js`. |
64+
| `--idl`, `-i` | Overrides the `idl` field in your configuration file. |
65+
66+
## Configuration file
67+
68+
> [!NOTE]
69+
> If you don't have a Codama configuration file yet, you can generate a new one using the `codama init` command as [described above](#codama-init).
4270
43-
The codama configuration file defines an object containing the following fields:
71+
The Codama configuration file defines an object containing the following fields:
4472

4573
- `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.
46-
- `before` (array): An array of visitors that will run before every script.
74+
```json
75+
{
76+
"idl": "path/to/idl"
77+
}
78+
```
79+
- `before` (array): An array of visitors that will run before every script. See [the next section](#using-visitors) for more details on how to use visitors in your configuration file.
80+
```json
81+
{
82+
"before": ["./my-visitor.js", "external-library#someVisitor"]
83+
}
84+
```
4785
- `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.
86+
```json
87+
{
88+
"scripts": {
89+
"apple": ["./my-apple-visitor.js"],
90+
"banana": ["./my-banana-visitor.js"]
91+
}
92+
}
93+
```
94+
95+
Whether it is in the `before` array or in the `scripts` values, if you have a single visitor, you may provide it directly instead of wrapping it in an array. For instance, the following configuration file is valid:
96+
97+
```json
98+
{
99+
"idl": "path/to/idl",
100+
"before": "./my-visitor.js",
101+
"scripts": { "apple": "./my-apple-visitor.js" }
102+
}
103+
```
48104

49-
Whether it is in the `before` array or in the `scripts` values, when defining a visitor you may either provide:
105+
Note that the configuration file can also be a JavaScript file exporting the configuration object as the `default` export.
50106

51-
- an object with the following fields:
52-
- `from` (string): The import path to the visitor.
53-
- `args` (array): An array of arguments to pass to the visitor.
54-
- a string: The import path to the visitor. This is equivalent to providing an object with a `from` field and an empty `args` array.
107+
```js
108+
export default {
109+
idl: 'path/to/idl',
110+
before: './my-visitor.js',
111+
scripts: { apple: './my-apple-visitor.js' },
112+
};
113+
```
114+
115+
## Using visitors
116+
117+
When using a visitor in your configuration file, **you must provide its import path**. This can either be a local path (relative or absolute) or an external NPM package. For instance the following are all valid visitor import paths:
118+
119+
```js
120+
'./my-visitor.js'; // Relative local path.
121+
'/Users/me/my-visitor.js'; // Absolute local path.
122+
'some-library'; // External package.
123+
'@acme/some-library'; // Scoped external package.
124+
```
55125

56-
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:
126+
In all these cases, the visitor will be imported from the `default` export of the module by default. If you want to **import a named export** instead, you may append a `#` followed by the export name to the import path. For instance:
57127

58128
```js
59-
'./my-visitor.js'; // Relative local path to a visitor module.
60-
'/Users/me/my-visitor.js'; // Absolute local path to a visitor module.
61-
'some-library'; // npm package name.
62-
'@acme/some-library'; // Scoped npm package name.
63129
'./my-visitor.js#myExport'; // Named export from a local path.
64-
'@acme/some-library#myExport'; // Named export from an npm package.
130+
'@acme/some-library#myExport'; // Named export from an external package.
65131
```
66132

67-
Here is an example of what a Codama configuration file might look like:
133+
Some visitors may instead be **exported as functions** that return visitor objects. This allows the visitor to receive arguments from the end-user to customize its behavior. When that is the case, you may instead define your visitor as an object with the following fields:
134+
135+
- `from` (string): The import path (and potentially the export name) of the visitor.
136+
- `args` (array): An array of arguments to pass to the visitor. If you don't need to pass any arguments to the visitor function, you may simply provide the import path as a string instead of an object.
68137

69138
```json
70139
{
71-
"idl": "path/to/idl",
72-
"before": [
73-
"./my-before-visitor.js",
74-
{ "from": "some-library#removeTypes", "args": [["internalFoo", "internalBar"]] }
75-
],
76-
"scripts": {
77-
"js": [
78-
{
79-
"from": "@codama/renderers-js",
80-
"args": ["clients/js/src/generated"]
81-
}
82-
]
83-
}
140+
"from": "@acme/some-library#myExport",
141+
"args": ["hello", { "someOption": true }]
84142
}
85143
```
86144

87-
Note that you can use the `--js` flag to generate a `.js` configuration file when running the `init` command.
145+
Finally note that, if the invoked visitor returns a new `RootNode`, this new `RootNode` will be used for the subsequent visitors instead of the original one. This allows us to chain visitors that modify the Codama IDL. Consider the following example such that the `./delete-all-accounts.js` visitor returns a new IDL with all accounts removed it.
146+
147+
```js
148+
export default {
149+
scripts: {
150+
documentation: [
151+
'./delete-all-accounts.js', // After this visitor, the IDL has no accounts.
152+
'./generate-documentation.js', // Generates documentation for an IDL with no accounts.
153+
],
154+
},
155+
};
156+
```
157+
158+
## Recipes
159+
160+
There are plenty of existing visitors that you can use in your Codama scripts. The "[Available visitors](https://github.com/codama-idl/codama?tab=readme-ov-file#available-visitors)" section of the Codama README aims to list as many of them as possible. This includes visitors maintained by various teams across the ecosystem.
161+
162+
The examples below show how to use some of these visitors in your configuration file. They make heavy use of the [`@codama/visitors`](https://github.com/codama-idl/codama/tree/main/packages/visitors/README.md) package which provides a large number of utility visitors.
163+
164+
### Deleting nodes
165+
166+
Returns a new IDL with the specified nodes removed.
167+
168+
See [`deleteNodesVisitor`](https://github.com/codama-idl/codama/tree/main/packages/visitors-core#deletenodesvisitor) and [node selectors](https://github.com/codama-idl/codama/tree/main/packages/visitors-core#selecting-nodes).
169+
170+
In the example below, we remove the `mint` account, the `initializeMint` instruction and all errors from the IDL.
171+
172+
```json
173+
{
174+
"from": "@codama/visitors#deleteNodesVisitor",
175+
"args": [["[accountNode]mint", "[instructionNode]initializeMint", "[errorNode]"]]
176+
}
177+
```
178+
179+
### Generating a JavaScript client
180+
181+
Generates a JavaScript client for the IDL at the specified output path.
182+
183+
See [`@codama/renderer-js`](https://github.com/codama-idl/renderers-js).
184+
185+
```json
186+
{
187+
"from": "@codama/renderers-js",
188+
"args": ["clients/js/src/generated"]
189+
}
190+
```
191+
192+
### Removing documentation
193+
194+
Returns a new IDL with documentation removed from all nodes.
195+
196+
See [`removeDocsVisitor`](https://github.com/codama-idl/codama/tree/main/packages/visitors-core#removedocsvisitor)
197+
198+
```json
199+
"@codama/visitors#removeDocsVisitor"
200+
```
201+
202+
### Unwrapping linked types
203+
204+
Returns a new IDL with specified type links replaced by their underlying types.
205+
206+
See [`unwrapDefinedTypesVisitor`](https://github.com/codama-idl/codama/tree/main/packages/visitors#unwrapDefinedTypesVisitor)
207+
208+
In the example below, any links to the `counter` or `escrow` types will be replaced by the actual definitions of these types.
209+
210+
```json
211+
{
212+
"from": "@codama/visitors#unwrapDefinedTypesVisitor",
213+
"args": [["counter", "escrow"]]
214+
}
215+
```
216+
217+
### Updating accounts
218+
219+
Returns a new IDL with updated account information.
220+
221+
See [`updateAccountsVisitor`](https://github.com/codama-idl/codama/tree/main/packages/visitors#updateAccountsVisitor)
222+
223+
In the example below, we rename the `vault` account to `safe` and update the `authority` field of the `bank` account to `treasury`.
224+
225+
```json
226+
{
227+
"from": "@codama/visitors#updateAccountsVisitor",
228+
"args": [
229+
{
230+
"vault": {
231+
"name": "safe"
232+
},
233+
"bank": {
234+
"data": { "authority": "treasury" }
235+
}
236+
}
237+
]
238+
}
239+
```

0 commit comments

Comments
 (0)