CLI

Run the Kodine CLI with no arguments and it launches the TUI.

kodine

It also takes the commands documented on this page, which is how you drive Kodine programmatically.

kodine run "Explain how closures work in JavaScript"

---

tui

Launches Kodine’s terminal user interface.

kodine [project]

Flags

Flag	Short	Description
--continue	-c	Pick up the most recent session
--session	-s	ID of the session to pick up
--fork		Fork the session while continuing (pair with --continue or --session)
--prompt		Prompt to start with
--model	-m	Model, written as provider/model
--agent		Agent to run
--auto		Automatically approve permissions that aren’t explicitly denied
--port		Port to listen on
--hostname		Hostname to listen on
--mdns		Turn on mDNS discovery
--mdns-domain		Custom mDNS domain name
--cors		Extra browser origin(s) to allow via CORS

---

Commands

Below are the commands the Kodine CLI offers.

---

agent

Manage Kodine agents.

kodine agent [command]

---

create

Scaffold a new agent with custom configuration.

kodine agent create

The command walks you through building an agent with its own system prompt and permission setup. In the generated frontmatter, anything you didn’t allow ends up denied.

Flags

Flag	Short	Description
--path		Where to write the agent file (defaults to the global location or .kodine/agent, depending on the prompt)
--description		What the agent should do
--mode		Agent mode: all, primary, or subagent
--permissions		Comma-separated permissions to allow (default: all). Available: bash, read, edit, glob, grep, webfetch, task, todowrite, websearch, lsp, skill. Anything omitted is denied. Alias: --tools
--model	-m	Model, in provider/model format

Supplying --path, --description, --mode, and --permissions together makes the command run without prompting.

---

list

Print every available agent.

kodine agent list

---

attach

Connect a terminal to a Kodine backend server that’s already running (started with serve or web).

kodine attach [url]

That’s how you use the TUI against a remote Kodine backend. For example:

# Spin up the backend server for web/mobile access
kodine web --port 4096 --hostname 0.0.0.0

# From a second terminal, attach the TUI to the running backend
kodine attach http://10.20.30.40:4096

Flags

Flag	Short	Description
--dir		Working directory the TUI starts in
--continue	-c	Pick up the most recent session
--session	-s	ID of the session to pick up
--fork		Fork the session while continuing (pair with --continue or --session)
--password	-p	Basic auth password (falls back to KODINE_SERVER_PASSWORD)
--username	-u	Basic auth username (falls back to KODINE_SERVER_USERNAME or kodine)

---

auth

Manage provider credentials and logins.

kodine auth [command]

---

login

Kodine draws its provider list from Models.dev, so kodine auth login can set up API keys for whichever provider you want to use. Credentials live in ~/.local/share/kodine/auth.json.

kodine auth login

At startup, Kodine reads providers from that credentials file, plus any keys present in your environment or in a project .env file.

Flags

Flag	Short	Description
--provider	-p	ID or name of the provider to log in to
--method	-m	Label of the login method to use, skipping the method picker

---

list

Print every authenticated provider found in the credentials file.

kodine auth list

Or the short form.

kodine auth ls

---

logout

Sign out of a provider by removing it from the credentials file.

kodine auth logout

---

github

Manage the GitHub agent used for repository automation.

kodine github [command]

---

install

Set up the GitHub agent in a repository.

kodine github install

This creates the required GitHub Actions workflow and walks you through configuration. Learn more.

---

run

Execute the GitHub agent — normally from inside GitHub Actions.

kodine github run

Flags

Flag	Description
--event	GitHub mock event the agent should run for
--token	GitHub personal access token

---

mcp

Manage Model Context Protocol servers.

kodine mcp [command]

---

add

Register an MCP server in your configuration.

kodine mcp add

The command walks you through connecting either a local or a remote MCP server.

---

list

Show every configured MCP server along with its connection status.

kodine mcp list

Or the short form.

kodine mcp ls

---

auth

Sign in to an OAuth-enabled MCP server.

kodine mcp auth [name]

Without a server name, you’ll get a picker listing the OAuth-capable servers.

You can also view OAuth-capable servers together with their auth status.

kodine mcp auth list

Or the short form.

kodine mcp auth ls

---

logout

Delete OAuth credentials for an MCP server.

kodine mcp logout [name]

---

debug

Troubleshoot OAuth connection problems for an MCP server.

kodine mcp debug <name>

---

models

Print every model offered by your configured providers.

kodine models [provider]

Output covers all configured providers and is written in the provider/model format.

Handy for finding the exact model identifier to put in your config.

Pass a provider ID to narrow the list down to that provider.

kodine models anthropic

Flags

Flag	Description
--refresh	Re-fetch the models cache from models.dev
--verbose	Print richer model output, including metadata such as costs

Reach for --refresh when the cached model list needs updating — for example after a provider adds new models that Kodine should see.

kodine models --refresh

---

run

Run Kodine non-interactively by handing it a prompt directly.

kodine run [message..]

Great for scripts, automation, or quick answers where spinning up the full TUI would be overkill. For example.

kodine run Explain the use of context in Go

Attaching to a running kodine serve instance also avoids paying MCP server cold-start time on each run:

# Spin up a headless server in one terminal
kodine serve

# From another terminal, run commands against it
kodine run --attach http://localhost:4096 "Explain async/await in JavaScript"

Flags

Flag	Short	Description
--command		Command to execute; the message becomes its args
--continue	-c	Pick up the most recent session
--session	-s	ID of the session to pick up
--fork		Fork the session while continuing (pair with --continue or --session)
--share		Share the session
--model	-m	Model, written as provider/model
--agent		Agent to run
--file	-f	File(s) to attach to the message
--format		Format: default (formatted) or json (raw JSON events)
--title		Session title (falls back to a truncated prompt when omitted)
--attach		Attach to a running kodine server (e.g., http://localhost:4096)
--password	-p	Basic auth password (falls back to KODINE_SERVER_PASSWORD)
--username	-u	Basic auth username (falls back to KODINE_SERVER_USERNAME or kodine)
--dir		Directory to run in, or a path on the remote server when attaching
--port		Port for the local server (random by default)
--variant		Model variant (provider-specific reasoning effort)
--thinking		Show thinking blocks
--auto		Automatically approve permissions that aren’t explicitly denied

---

serve

Launch a headless Kodine server for API access. The server docs describe the full HTTP interface.

kodine serve

This brings up an HTTP server exposing Kodine’s functionality without the TUI. Set KODINE_SERVER_PASSWORD to turn on HTTP basic auth (the username defaults to kodine).

Flags

Flag	Description
--port	Port to listen on
--hostname	Hostname to listen on
--mdns	Turn on mDNS discovery
--mdns-domain	Custom mDNS domain name
--cors	Extra browser origin(s) to allow via CORS

---

session

Manage Kodine sessions.

kodine session [command]

---

list

Print every Kodine session.

kodine session list

Flags

Flag	Short	Description
--max-count	-n	Cap output at the N most recent sessions
--format		Output format: table or json (table)

---

delete

Remove a Kodine session.

kodine session delete <sessionID>

---

stats

Print token usage and cost stats across your Kodine sessions.

kodine stats

Flags

Flag	Description
--days	Limit stats to the last N days (all time)
--tools	How many tools to show (all)
--models	Show the model usage breakdown (hidden unless requested). Pass a number for the top N
--project	Filter by project (all projects, empty string: current project)

---

export

Write session data out as JSON.

kodine export [sessionID]

Without a session ID, you’ll get a picker of available sessions.

Flags

Flag	Description
--sanitize	Strip sensitive transcript/file data

---

import

Load session data from a JSON file or a Kodine share URL.

kodine import <file>

Both local files and Kodine share URLs work as sources.

kodine import session.json
kodine import https://kodine.net/s/abc123

---

web

Launch a headless Kodine server that serves a web interface.

kodine web

This brings up an HTTP server and opens a browser so you can use Kodine through the web UI. Set KODINE_SERVER_PASSWORD to turn on HTTP basic auth (the username defaults to kodine).

Flags

Flag	Description
--port	Port to listen on
--hostname	Hostname to listen on
--mdns	Turn on mDNS discovery
--mdns-domain	Custom mDNS domain name
--cors	Extra browser origin(s) to allow via CORS

---

acp

Launch an ACP (Agent Client Protocol) server.

kodine acp

The ACP server talks over stdin/stdout using nd-JSON.

Flags

Flag	Description
--cwd	Working directory
--port	Port to listen on
--hostname	Hostname to listen on
--mdns	Turn on mDNS discovery
--mdns-domain	Custom mDNS domain name
--cors	Extra browser origin(s) to allow via CORS

---

plugin

Install a plugin and update your config.

kodine plugin <module>

Or via the alias.

kodine plug <module>

Flags

Flag	Short	Description
--global	-g	Install into the global config
--force	-f	Overwrite an existing plugin version

---

pr

Check out a GitHub PR branch and launch Kodine on it.

kodine pr <number>

---

db

Database utilities.

kodine db [query]

Flags

Flag	Description
--format	Output format: json or tsv

---

path

Print where the database lives.

kodine db path

---

debug

Tools for debugging and troubleshooting.

kodine debug [command]

---

uninstall

Remove Kodine along with its related files.

kodine uninstall

Flags

Flag	Short	Description
--keep-config	-c	Leave configuration files in place
--keep-data	-d	Leave session data and snapshots in place
--dry-run		Print what would be removed, without removing it
--force	-f	Don’t ask for confirmation

---

upgrade

Bring Kodine up to the newest version, or to one you choose.

kodine upgrade [target]

Upgrade to the newest version.

kodine upgrade

Upgrade to a chosen version.

kodine upgrade v0.1.48

Flags

Flag	Short	Description
--method	-m	How it was installed: curl, npm, pnpm, bun, brew

---

Global Flags

These global flags work on the kodine CLI itself.

Flag	Short	Description
--help	-h	Show help
--version	-v	Print the version number
--print-logs		Write logs to stderr
--log-level		Log level (DEBUG, INFO, WARN, ERROR)
--pure		Run with external plugins disabled

---

Environment variables

Environment variables offer another way to configure Kodine.

Variable	Type	Description
KODINE_AUTO_SHARE	boolean	Share sessions automatically
KODINE_GIT_BASH_PATH	string	Where the Git Bash executable lives on Windows
KODINE_CONFIG	string	Path to the config file
KODINE_TUI_CONFIG	string	Path to the TUI config file
KODINE_CONFIG_DIR	string	Path to the config directory
KODINE_CONFIG_CONTENT	string	Inline JSON config content
KODINE_DISABLE_AUTOUPDATE	boolean	Turn off automatic update checks
KODINE_DISABLE_PRUNE	boolean	Turn off pruning of old data
KODINE_DISABLE_TERMINAL_TITLE	boolean	Turn off automatic terminal title updates
KODINE_PERMISSION	string	Inline JSON permissions config
KODINE_DISABLE_DEFAULT_PLUGINS	boolean	Turn off default plugins
KODINE_DISABLE_LSP_DOWNLOAD	boolean	Turn off automatic LSP server downloads
KODINE_ENABLE_EXPERIMENTAL_MODELS	boolean	Turn on experimental models
KODINE_DISABLE_AUTOCOMPACT	boolean	Turn off automatic context compaction
KODINE_DISABLE_CLAUDE_CODE	boolean	Stop reading from .claude (prompt + skills)
KODINE_DISABLE_CLAUDE_CODE_PROMPT	boolean	Stop reading ~/.claude/CLAUDE.md
KODINE_DISABLE_CLAUDE_CODE_SKILLS	boolean	Stop loading .claude/skills
KODINE_DISABLE_MODELS_FETCH	boolean	Stop fetching models from remote sources
KODINE_DISABLE_MOUSE	boolean	Turn off mouse capture in the TUI
KODINE_FAKE_VCS	string	Fake VCS provider for testing purposes
KODINE_CLIENT	string	Client identifier (defaults to cli)
KODINE_ENABLE_EXA	boolean	Turn on Exa web search tools
KODINE_ENABLE_PARALLEL	boolean	Turn on Parallel web search tools
KODINE_SERVER_PASSWORD	string	Turn on basic auth for serve/web
KODINE_SERVER_USERNAME	string	Override the basic auth username (default kodine)
KODINE_MODELS_URL	string	Custom URL for fetching model configuration

---

Experimental

These variables switch on experimental features that may change or disappear.

Variable	Type	Description
KODINE_EXPERIMENTAL	boolean	Master switch for experimental features
KODINE_EXPERIMENTAL_ICON_DISCOVERY	boolean	Turn on icon discovery
KODINE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT	boolean	Turn off copy-on-select in the TUI
KODINE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS	number	Default bash command timeout, in ms
KODINE_EXPERIMENTAL_OUTPUT_TOKEN_MAX	number	Cap on output tokens for LLM responses
KODINE_EXPERIMENTAL_FILEWATCHER	boolean	Turn on the file watcher for the whole directory
KODINE_EXPERIMENTAL_OXFMT	boolean	Turn on the oxfmt formatter
KODINE_EXPERIMENTAL_LSP_TOOL	boolean	Turn on the experimental LSP tool
KODINE_EXPERIMENTAL_DISABLE_FILEWATCHER	boolean	Turn off the file watcher
KODINE_EXPERIMENTAL_EXA	boolean	Turn on experimental Exa features
KODINE_EXPERIMENTAL_LSP_TY	boolean	Turn on the TY LSP for Python files
KODINE_EXPERIMENTAL_PLAN_MODE	boolean	Turn on plan mode
KODINE_EXPERIMENTAL_BACKGROUND_SUBAGENTS	boolean	Turn on background subagent tasks
KODINE_EXPERIMENTAL_EVENT_SYSTEM	boolean	Turn on the experimental event system
KODINE_EXPERIMENTAL_NATIVE_LLM	boolean	Turn on the native LLM request path
KODINE_EXPERIMENTAL_PARALLEL	boolean	Turn on parallel web search execution
KODINE_EXPERIMENTAL_SCOUT	boolean	Turn on the Scout subagent
KODINE_EXPERIMENTAL_WORKSPACES	boolean	Turn on workspace support