Skip to content
Katachi

Agent Commands

Overview

Section titled “Overview”

The katachi CLI manages the agent daemon running on your machine. Here’s every command you need to know.

katachi start

Section titled “katachi start”

Start the agent daemon. On first run, guides you through device-flow authentication.

Terminal window
katachi start                  # Start with defaults
katachi start --port 3001      # Custom port
katachi start --debug          # Enable debug logging
katachi start --home ~/my-dir  # Custom data directory

The agent runs as a background process via PM2, so it survives terminal closures.

katachi stop

Section titled “katachi stop”

Stop the agent daemon.

Terminal window
katachi stop

This also disconnects the Cloudflare tunnel.

katachi restart

Section titled “katachi restart”

Restart the agent daemon. Preserves the current port configuration.

Terminal window
katachi restart

katachi status

Section titled “katachi status”

Check if the agent is running and view tunnel information.

Terminal window
katachi status

Output includes PID, port, memory usage, uptime, and tunnel URL.

katachi logs

Section titled “katachi logs”

View agent logs.

Terminal window
katachi logs          # Show recent logs
katachi logs -f       # Follow logs in real-time (tail -f)
katachi logs -n 50    # Show last 50 lines

katachi version

Section titled “katachi version”

Display version information.

Terminal window
katachi version

katachi unregister

Section titled “katachi unregister”

Deregister the agent from Katachi servers and remove local credentials.

Terminal window
katachi unregister          # Normal: deregister from backend first
katachi unregister --force  # Force: remove local credentials even if backend is unreachable
katachi unregister -y       # Skip confirmation prompt