---
title: "Kodama CLI reference: kodactl and kodama"
description: "Reference for kodactl, the Kodama command-line client, and for the kodama binary: installation, configuration, every command, output formats and exit codes."
canonical_url: https://optimi.com/en/docs/kodama/cli
md_url: https://optimi.com/en/docs/kodama/cli.md
language: en
alternates:
  - lang: fr
    url: https://optimi.com/fr/docs/kodama/cli
    md_url: https://optimi.com/fr/docs/kodama/cli.md
last_updated: 2026-11-14
---

# CLI reference

Kodama ships two binaries:

| Binary | Role |
| --- | --- |
| `kodactl` | The command-line client. It calls the REST API, so it works from a laptop, from CI and from inside a pipeline container |
| `kodama` | The server binary. On a workstation you use `kodama up`, `kodama down` and `kodama status`; the other commands run the services of an installation |

Both come from the same release, and
`curl -fsSL https://raw.githubusercontent.com/optimiware/kodama/master/install.sh | sh`
installs both. `kodactl version` and `kodama version` print the version and
the source revision.

## Configure kodactl

After `kodama up`, one line is enough:

```sh
source ~/.kodama/instances/default/env.sh
```

For another installation, set the same values yourself. Every global flag has
an environment variable:

| Flag | Variable | Meaning |
| --- | --- | --- |
| `--url` (also `--server`, `--server-url`) | `KODAMA_URL`, `KODAMA_SERVER` | The Kodama server URL |
| `--ca-file` | `KODAMA_CA_FILE` | PEM CA bundle, for an installation with a private CA |
| `--project` | `KODAMA_PROJECT` | The default project |
| `--output` | `KODAMA_OUTPUT` | `table` (default) or `json` |
| `--credential-file` | `KODAMA_CREDENTIAL_FILE` | A file that holds a token: an administrator or service token, or the mounted execution token |
| `--session` (also `--session-file`) | `KODAMA_SESSION` | The file that keeps the session of `kodactl login` |
| `--config` | `KODAMA_CONFIG` | A configuration file |

Two ways to authenticate:

- **A person** runs `kodactl login`. The session is saved and refreshed for the
  following commands.
- **Automation** points `KODAMA_CREDENTIAL_FILE` at a token file. Inside a
  pipeline container, `kodactl` reads the mounted execution credential by
  default.

`env.sh` sets `KODAMA_CREDENTIAL_FILE` to an administrator token. Unset it to
use your own session.

## Sign in

| Command | Effect |
| --- | --- |
| `kodactl login` | Sign in with the browser (OIDC with PKCE). `--device` or `--no-browser` uses the device flow, for a machine without a browser |
| `kodactl logout` | Revoke the refresh token and delete the local session |
| `kodactl refresh` | Rotate the stored session before it expires |
| `kodactl status` | Show the issuer, the server URL and the expiry of the session |
| `kodactl whoami` | Show your principal, its kind, scope and roles. `--offline` derives it from the saved session without calling the server |

## Run and observe

| Command | Effect |
| --- | --- |
| `kodactl run <file> [--input k=v]` | Start a local pipeline file inline and follow it to its end. Nothing is stored |
| `kodactl inspect <execution-id>` | Show an execution and its actions |
| `kodactl watch <execution-id>` | Poll until the execution ends |
| `kodactl logs <execution-id> [--action <name>] [--stream stdout\|stderr] [-f]` | Read the retained log of an action; `-f` follows until the action ends |
| `kodactl pipeline apply <directory\|file>` | Store every `.yaml` and `.yml` file of a directory, or one file, and print each pipeline ID |

`run` prints the standard output of each container action, in action order,
when the execution ends; the execution ID and the outcome go to standard
error. Without `--action`, `logs` selects the running action, or the last one
that started.

## Answer the inbox

| Command | Effect |
| --- | --- |
| `kodactl inbox` | List pending approvals, waiting tasks and failed tasks for your roles |
| `kodactl approve <execution-id> [--comment <text>] [--output k=v]` | Answer the waiting request with `pass` |
| `kodactl reject <execution-id> --reason <text> [--output k=v]` | Answer it with `fail`; the reason is required |

`approve` and `reject` find the waiting request of the execution themselves.
Use `--action <id>` to name it. `--output` fills a response field that the
request declared, and can be repeated.

## Tasks

| Command | Effect |
| --- | --- |
| `kodactl task create --title <t> [--description <d>] [--pipeline <id>] [--input k=v]` | Create an open task; nothing starts |
| `kodactl task run --title <t> --pipeline <id> [--description <d>] [--input k=v]` | Create a task and start it at once |
| `kodactl task list` | List the tasks of the project |
| `kodactl task show <task-id>` | Show the state, the versions and the outstanding question; `--output json` adds the messages |
| `kodactl task start <task-id>` | Start a new execution of an existing task |
| `kodactl task reply <task-id> --answer <text>` | Answer the outstanding question of a waiting task; a fresh execution is queued |
| `kodactl task cancel <task-id>` | Cancel a task and its running execution |

`start` and `cancel` read the current version of the task themselves; pass
`--expected-version <v>` to pin the version you looked at.

## Members

| Command | Effect |
| --- | --- |
| `kodactl member list` | List the memberships of the project and their versions |
| `kodactl member grant <principal-or-subject> --role <role>[,<role>…]` | Set the complete role set of a principal: `admin`, `engineer`, `reviewer`, `operator`, `viewer` |
| `kodactl member revoke <principal-or-subject>` | Remove a membership |

A target that starts with `oidc-` is used as it is. Otherwise pass an OIDC
subject, or `--github <login>`, and `kodactl` derives the principal ID from
the issuer. On the local installation these commands need the tenant-wide
administrator token:

```sh
kodactl --credential-file "$KODAMA_TENANT_ADMIN_CREDENTIAL_FILE" member list
```

## MCP

| Command | Effect |
| --- | --- |
| `kodactl mcp install [claude\|cursor\|codex]` | Write the Kodama entry into the client’s MCP configuration |
| `kodactl mcp stdio` | Bridge JSON-RPC on standard input and output to the server’s `/mcp` endpoint, with your credential |

`mcp install` accepts `--print` to show the snippet without writing a file,
`--name` to rename the server (default `kodama`), `--config-file` for an
explicit path, and `--local` to write `.mcp.json` in the current directory
(Claude only). The default files are `~/.claude.json`, `~/.cursor/mcp.json`
and `~/.codex/config.toml`.

## Call any operation

`kodactl call` invokes any of the public operations by name, with a JSON input:

```sh
kodactl call execution.list --input='{"project_id":"project-local"}'
KODAMA_OUTPUT=json kodactl call task.read --input='{"task_id":"<task-id>"}'
kodactl call task.cancel --input='{"task_id":"<task-id>"}' \
  --expected-version=3 --idempotency-key=cancel-task-1
```

The three flags are written `--flag=value`. The input carries the identifiers
that the REST route has in its path, such as `project_id` or `task_id`.
`--expected-version` and `--idempotency-key` map to the fields of the request
envelope described in **[API and MCP](/en/docs/kodama/api)**, which also lists
the operations.

## Git credential helper

`kodactl helper <get|store|erase>` is a Git credential helper. It supplies your
current access token, or the mounted execution token inside a container, as
the password of the user `kodama`, and only to the Git origins the installation
registers as trusted.

## Output and exit codes

Tables are the default. `--output json`, or `KODAMA_OUTPUT=json`, prints JSON
for scripts.

| Code | Meaning |
| --- | --- |
| 0 | Success. For `run` and `watch`: the execution succeeded |
| 1 | Failure. For `run` and `watch`: the execution failed or was cancelled. `run` also exits 1 when the execution stops at a request that waits for a person |
| 2 | Usage error |

`kodactl help <command>` prints the usage of a command.

## The kodama binary

**On a workstation**

| Command | Effect |
| --- | --- |
| `kodama up` | Start a local Kodama on Podman, or renew its credentials when it runs |
| `kodama status` | Inspect the local Kodama; `--json` prints the report as JSON |
| `kodama down` | Stop it and keep the state; `--purge` removes the volumes and the state directory |

| `kodama up` flag | Variable | Default |
| --- | --- | --- |
| `--name` | `KODAMA_INSTANCE` | `default` |
| `--state-dir` | `KODAMA_UP_STATE_DIR` | `~/.kodama/instances/<name>` |
| `--listen` | `KODAMA_UP_LISTEN` | Port 8443 |
| `--tenant` | `KODAMA_UP_TENANT` | `tenant-local` |
| `--project` | `KODAMA_UP_PROJECT` | `project-local` |
| `--image` | `KODAMA_UP_IMAGE` | The released image of the binary’s version |
| `--socket` | `KODAMA_UP_SOCKET` | The user’s Podman socket |

**In an installation**

| Command | Effect |
| --- | --- |
| `kodama server` | Run the control plane (`--profile development`, `test` or `production`) |
| `kodama migrate` | Apply the database migrations and set the role passwords |
| `kodama bootstrap-admin` | Create the first tenant and administrator from an OIDC token |
| `kodama git serve` | Run the Git smart-HTTP service |
| `kodama git provision-tenant` | Create the tenant’s `admin` repository |
| `kodama git provision-repository` | Initialize a repository and commit its default access rules |
| `kodama auth serve` | Run the built-in OIDC provider and social sign-in broker |
| `kodama auth principal-id` | Derive the principal ID of an OIDC issuer and subject |
| `kodama services` | Run one service adapter |
| `kodama agent` | Run one bounded native-agent run |

`kodama <command> --help` prints the flags of a command.
**[Operations](/en/docs/kodama/operations)** shows where each one is used.