CLI Reference

The dkod CLI (dk) is a human-facing, Git-compatible command-line tool built in Rust. It's a drop-in replacement for git that adds dkod-specific commands for agent management and semantic operations.

Installation

cargo install dk-cli

Or install from source: cargo install --git https://github.com/dkod-io/dkod-engine dk-cli

Or download a prebuilt binary from the releases page.

Git-Compatible Commands

Every standard Git command works as expected. dk uses gitoxide under the hood — a pure-Rust Git implementation that's 3–5x faster than C Git on many operations.

dk git clone <url>      # Clone a repository
dk git pull             # Pull from remote
dk git branch <name>    # Create a branch
dk git checkout <branch># Switch branches
dk git log              # View commit history

All existing Git workflows, hooks, and tooling are fully compatible. Git operations live under the dk git namespace.

dkod-Specific Commands

These commands are unique to dkod and have no Git equivalent:

dk login                    # Authenticate via browser (device flow)
dk init                     # Open a session on a dkod codebase (cloud)
dk --server <addr> init     # Connect to a self-hosted engine (--server is a global flag)
dk search                   # Semantic code search
dk cat                      # Read a file from the workspace
dk ls                       # List files in the workspace
dk check                    # Run verification pipeline
dk agent                    # Low-level Agent Protocol commands (advanced/internal)
dk repo                     # Manage repositories (create/list/delete)
dk index                    # Index a repository for semantic search

dkod Session Commands

Top-level commands are always session/agent commands — there is no mode switching:

Command	Description
`dk add <files>`	Write a file to the session workspace
`dk commit -m "msg"`	Submit changeset with intent description
`dk push`	Merge verified changeset and push to GitHub. Supports `--message` (`-m`) for commit message and `--force` to bypass recency guard.
`dk diff`	Show pending changes in the changeset
`dk status`	Show session state and pending changes

Git operations live under the dk git <command> namespace (e.g., dk git clone, dk git pull). These are separate commands, not modes of the same command.

Global Flags

All commands support the following flags:

Flag	Description
`--json`	Output results in machine-readable JSON format, useful for CI pipelines and scripting
`--quiet`	Suppress non-essential output
`--no-color`	Disable colored output
`--server`	Override the server address for this command

Environment Variables

Configure the CLI via environment variables for CI/automation workflows:

Variable	Description	Default
`DKOD_AUTH_TOKEN`	API token for authentication. Required when connecting to a remote dkod server.	—
`DKOD_GRPC_ADDR`	Server address for gRPC connections.	`https://agent.dkod.io:443`

Example CI usage:

export DKOD_AUTH_TOKEN="dk_live_..."
export DKOD_GRPC_ADDR="https://agent.dkod.io:443"
dk init my-project
dk check

Server Configuration

The dkod engine is configured via CLI flags and environment variables — there is no config file.

Flag	Environment Variable	Description	Default
`--database-url`	`DATABASE_URL`	PostgreSQL connection string (required)	—
`--storage-path`	`DKOD_STORAGE_PATH`	Local file storage path	`./storage`
`--listen-addr`	`DKOD_LISTEN_ADDR`	gRPC listen address	`[::1]:50051`
`--auth-token`	`DKOD_AUTH_TOKEN`	Shared agent authentication token	—
`--jwt-secret`	`JWT_SECRET`	HMAC-SHA256 secret for JWT auth	—

Note: Either --auth-token or --jwt-secret (or both for dual-mode) must be provided. The server supports multiple authentication modes: JWT, Shared Secret, Dual (both), or External (pass-through).

CLI Configuration

The CLI uses three configuration files:

~/.config/dkod/token.json — auth token, created by dk login (device flow)
~/.config/dkod/config.toml — CLI settings (server URL, preferences)
~/.config/dkod/session.json — active session state, created by dk init

The token and session files are managed automatically. The config file can be edited manually if needed.

Performance

The CLI is built on gitoxide, which benchmarks significantly faster than C Git:

Checkouts: ~5x faster
Pack resolution: ~3x faster
Object iteration: ~2x faster
Memory usage: Lower due to Rust's memory model

Next Steps

SDK Reference — the agent-facing SDK
Quickstart — get started with the CLI
Agent Protocol — understand the protocol behind the commands