CLI Reference

Global Options

These flags can be used with any command:

kod [global options] <command> [options]

  -t, --token <token>    API token for authentication
  -s, --server <url>     Server URL (default: http://localhost:3000)
  -h, --help             Show help
  -v, --version          Show version

`kod init`

Configure the CLI client interactively. Saves settings to ~/.kod/config.json.

kod init

When prompted for the API token, enter the same token used with --admin-token when starting the server.

If git-credential-kod is available on your PATH (installed automatically with npm install -g kod), kod init also configures Git to use it as a credential helper for the server host. This means plain git clone, git push, and git pull will authenticate automatically.

`git-credential-kod`

A Git credential helper that reads your Kod token from ~/.kod/config.json and provides it to Git automatically. Installed alongside the kod binary.

You normally don’t need to invoke this directly — kod init configures Git to use it. To set it up manually:

git config --global credential.http://localhost:3000.helper kod

`kod serve`

Start the Kod server.

kod serve [options]

Options:
  --port, -p <port>          Port to listen on (default: 3000)
  --data-dir <path>          Data directory for database
  --repos-dir <path>         Directory for Git repositories
  --token <token>            API token for authentication
  --admin-token <token>      Admin token for first-time setup
  --encryption-key <key>     Encryption key for secrets

Environment variables:

Variable	Description
`KOD_PORT`	Port to listen on
`KOD_DATA_DIR`	Data directory
`KOD_REPOS_DIR`	Repos directory
`KOD_API_TOKEN`	API token
`KOD_ADMIN_TOKEN`	Admin token for first-time setup
`KOD_ENCRYPTION_KEY`	Encryption key for secrets

`kod clone`

Clone a repository using your configured token.

kod clone <repo-name>
kod clone <url>
kod clone my-app --credentials kod_other_token

`kod repo`

Manage repositories.

kod repo list                          # List all repositories
kod repo create <name>                 # Create a new repository
kod repo <name> info                   # Show repository details
kod repo update <name> name <new>      # Rename a repository
kod repo delete <name>                 # Delete a repository

Collaborators

kod repo <name> collaborator list              # List collaborators
kod repo <name> collaborator add <username>    # Add collaborator
kod repo <name> collaborator remove <username> # Remove collaborator

`kod token`

Manage API tokens (requires admin permission).

kod token list                         # List all tokens
kod token create <name> [options]      # Create a new token
kod token delete <id>                  # Delete a token

Create options:

--permissions <perms>   Comma-separated permissions (default: repo:read,repo:write,workflow:read)
--expires <days>        Token expiration in days (1-365)
--username <user>       Link token to a collaborator (for Git access)

Examples:

kod token create ci-deploy --permissions repo:read,workflow:trigger
kod token create alice --username alice --permissions repo:read,repo:write
kod token create temp --expires 30
kod token create full-admin --permissions admin

`kod workflow`

Run workflows locally or check status.

kod workflow <file.toml> [file2.toml...]   # Run workflow(s) locally
kod workflow status [repo]                 # Check workflow status

Examples:

kod workflow build.toml
kod workflow build.toml deploy.toml
BRANCH=main kod workflow build.toml
kod workflow status
kod workflow status my-repo

`kod upgrade`

Upgrade Kod to the latest version.

kod upgrade

`kod uninstall`

Remove Kod from your system. Deletes the binary (~/.local/bin/kod) and data directory (~/.kod). Prompts for confirmation before proceeding.

kod uninstall

Permissions

Permission	Description
`repo:read`	Clone and fetch repositories
`repo:write`	Push to repositories
`repo:delete`	Delete repositories
`collaborator:read`	List collaborators
`collaborator:write`	Add/remove collaborators
`workflow:read`	View workflow status and history
`workflow:trigger`	Trigger workflows via API
`secrets:read`	List secret names (no values)
`secrets:write`	Create, update, and delete secrets
`admin`	Full access to all operations