CLI Reference

Global Options

Flag	Description
-V, --version	Output version number
-h, --help	Display help

Commands

start

Start the Katachi agent daemon.

katachi start [options]

Flag	Default	Description
-p, --port <port>	7676	HTTP server port
-d, --debug	false	Enable debug logging
--home <dir>	~/.katachi	Agent data directory

Behavior:

• On first run, initiates device-flow authentication
• Starts the agent as a background process via PM2
• Establishes a Cloudflare tunnel to the backend
• Performs a health check after startup

---

stop

Stop the Katachi agent daemon.

katachi stop [options]

Flag	Default	Description
--home <dir>	~/.katachi	Agent data directory

---

restart

Restart the Katachi agent daemon.

katachi restart [options]

Flag	Default	Description
--home <dir>	~/.katachi	Agent data directory

Behavior: Detects current port configuration from the running process and restarts with the same settings.

---

status

Check agent daemon status and tunnel information.

katachi status [options]

Flag	Default	Description
--home <dir>	~/.katachi	Agent data directory

Output includes: PID, port, CPU usage, memory usage, uptime, tunnel URL.

---

logs

View agent logs.

katachi logs [options]

Flag	Default	Description
-f, --follow	false	Follow log output (like tail -f)
-n, --lines <n>	100	Number of lines to show
--home <dir>	~/.katachi	Agent data directory

---

version

Show version information.

katachi version

Output includes: Version number, Node.js version, platform, architecture.

---

unregister

Deregister the agent and remove all credentials.

katachi unregister [options]

Flag	Default	Description
--force	false	Remove local credentials even if backend is unreachable
-y, --yes	false	Skip confirmation prompt
--home <dir>	~/.katachi	Agent data directory

Behavior:

1. Stops the agent if running
2. Sends deregister request to backend (HMAC-authenticated)
3. Removes credentials from disk

With --force, ignores failures in step 2 (useful when the backend is unreachable).