CLI overview

Command-line interface for managing Kimaki Discord bot instances

Kimaki provides a comprehensive CLI for managing Discord bot instances, creating project channels, sending messages programmatically, and automating workflows.

Installation

The CLI is distributed via npm and can be run without installation:

npx -y kimaki@latest

For frequent use, install globally:

npm install -g kimaki

Command structure

All commands follow this pattern:

kimaki [command] [options]

Available commands

send

Start sessions programmatically from CI or automation

project add

Create Discord channels for project directories

project list

List all registered projects with their channels

session

Read and search session history

upload-to-discord

Upload files to Discord threads

task

Manage scheduled tasks

upgrade

Upgrade Kimaki to the latest version

Common options

These options work across multiple commands:

Option	Description
--data-dir <path>	Custom data directory (default: ~/.kimaki)
--help	Show help for a command
--version	Show Kimaki version

Environment variables

KIMAKI_BOT_TOKEN · string

Discord bot token for authentication. Required for CI/automation when bot credentials aren’t in the database.

KIMAKI_LOCK_PORT · number

Lock port for single-instance enforcement. Auto-derived from --data-dir if not set.

KIMAKI_VITEST · string

Set to 1 to suppress terminal log noise during test runs.

Exit codes

Code	Meaning
0	Success
1	General error
64	Exit without restart (used internally)

Interactive vs non-interactive mode

When you run kimaki without arguments, it enters interactive mode with a setup wizard:

kimaki

This guides you through:

1. Creating or selecting a Discord bot
2. Configuring bot settings
3. Installing the bot to servers
4. Adding project channels
5. Starting the bot process

For automation and CI, use non-interactive commands like send and project add with explicit arguments.

Best practices

Use --data-dir to run multiple isolated Kimaki instances on the same machine. Each instance gets its own database, projects, and lock port.

In CI environments, always set KIMAKI_BOT_TOKEN as a secret. Never commit bot tokens to version control.

The send command creates threads that trigger the bot running on your machine. Ensure the bot process is running before using CLI automation.

Next steps

Send command

Start sessions from CI pipelines

CI automation

GitHub Actions integration examples