Command reference

cardano-init [OPTIONS]            # create a project (interactive, or one-shot with --name)
cardano-init list                 # list roles and tools
cardano-init table                # compact matrix of tools by role
cardano-init doctor               # check this project's dependencies
cardano-init add [ROLE FLAGS]     # add or replace a tool in the current project
cardano-init remove [ROLE FLAGS]  # remove a role or infrastructure provider
cardano-init help [COMMAND]       # print help

Every command accepts the global --json flag (default: human-readable output). See For coding agents for the JSON output.

Every command also accepts the global --icons[=WHEN] flag. It shows an icon before each tool name: the tool’s language, or a terminal for tools you run (infrastructure, devnet). Icons need Nerd Font symbols in your terminal. WHEN is one of:

• auto (default): on in terminals that include Nerd Font symbols (Ghostty, WezTerm, kitty), when output goes to the terminal. Inside tmux or zellij the terminal can’t be recognized, so use always there.
• always (what plain --icons means): on, even when output is piped.
• never: off.

The CLI remembers the last value you passed, so you only need the flag once. The CARDANO_INIT_ICONS environment variable takes the same values and overrides the remembered one. Icons never appear in --json output.

Create a project

cardano-init                                       # interactive mode
cardano-init --name my-app --on-chain aiken        # one-shot, single role
cardano-init --name my-app --on-chain aiken --off-chain meshjs --nix
cardano-init -n my-app -p scalus -d yaci           # short flags

With --name, the command runs in one-shot mode and never prompts. Without it, the command starts the interactive setup. Any other creation flag without --name is an error (name_required).

Short flags and aliases behave exactly like the long flag. Errors and JSON output always use the long name. If the project directory already exists and is not empty, the command stops with dir_exists.

list

List the available roles and tools, including each tool’s language, status, documentation, supporting tooling, and community links.

cardano-init list                 # detailed, grouped by role
cardano-init list --json   # machine-readable catalog

table

Show a compact matrix of tools by role: one column per role, headed by the role with the flag that fills it below (for example --on-chain), each tool shown as its name followed by its id in parentheses, for example Aiken (aiken). Pass the id to the role flags, such as --on-chain aiken. Experimental tools are marked 🧪, and tools that also support --fullstack are marked 🧩.

cardano-init table

With --json, table prints the same catalog as list --json.

doctor

Run doctor inside a generated project. It finds the project’s components, checks that the toolchains they need are installed and recent enough, and prints the install command for each one that is missing and the upgrade command for each one that is too old. Add --links to also list the editor extensions, language servers, and community channels for the project’s tools.

cd my-protocol
cardano-init doctor
cardano-init doctor --links
cardano-init doctor --json

add

Add a tool to the project in the current directory, or replace the tool of a role. add takes the same role flags as project creation.

cardano-init add --on-chain plinth            # replace the on-chain tool
cardano-init add --devnet yaci                # add a devnet
cardano-init add --infra kupo --infra ogmios  # add infrastructure providers
cardano-init add --fullstack scalus           # switch to a fullstack protocol/ component

Plus the shared update flags.

remove

Remove a role, or one infrastructure provider, from the project in the current directory. Role flags take no value, except --infra, which takes the provider id.

cardano-init remove --devnet
cardano-init remove --infra ogmios
cardano-init remove --off-chain --formal-methods

Plus the shared update flags.

Shared update flags

add and remove read the project’s current tools from its component directories, apply the change, and update the shared top-level files (Justfile, README.md, AGENTS.md, …). By default they need a clean git working tree, so you can review the change with git diff and revert it.

Exit codes

For the exact error, use --json and read error.code. See Error codes.