Last updated: 2026-05-10

Command Reference

hicli pair

Pair with your phone via QR code. This is the main setup command.

hicli pair

What it does:

1. Gets your Tailscale IP (fails if Tailscale is not running)
2. Checks dependencies: sshd, mosh, tmux
3. Configures tmux mouse mode in ~/.tmux.conf
4. Installs AI tool notification hooks (Claude Code, Codex, Gemini)
5. Starts a temporary HTTP server to receive the phone’s SSH public key
6. Generates a QR code and waits for scanning (10-minute timeout)

Example output:

Checking Tailscale...
  Tailscale IP: 100.64.0.1
Checking dependencies...
  ✓ sshd is ready
  ✓ mosh is ready
  ✓ tmux is ready
  ✓ Notification hooks installed
  Key service:  http://100.64.0.1:54321/ssh-key

SSH Connection Info:
  Host:     100.64.0.1
  Port:     22
  Username: alice
  Name:     macbook-pro

Scan the QR code below with hitermux to add this PC:

Waiting for public key from phone (10min timeout)...
Public key received and added!
  → ~/.ssh/authorized_keys
You can now connect from hitermux!

If dependencies are missing, the command shows platform-specific install commands:

Checking dependencies...
  ⚠ sshd is not running
  ⚠ mosh is missing

  sshd: sudo systemsetup -setremotelogin on
  mosh: port install mosh

  Install the missing tools above, then re-run: hicli pair

After pairing, the phone’s SSH public key is added to ~/.ssh/authorized_keys. The QR code contains: TailscaleIP|Port|Username|Hostname|KeyPort.

Tip: If the 10-minute timeout expires, the SSH host info is still saved on the phone. You can re-run hicli pair to try again.

hicli doctor

Diagnose and auto-fix common configuration issues.

hicli doctor

Checks performed:

Example output:

hicli Doctor

  ✓ Tailscale        Running (100.64.0.1)
  ✓ Config           OK (0600)
  ✓ SSH Service      Listening on port 22
  ✓ mosh             Installed (/usr/local/bin/mosh)
  ✗ Notifications    Hooks not installed

  4 passed, 1 failed

Found issues that can be auto-fixed. Fix now? [Y/n]

Non-interactive mode: When running in a pipe or CI, doctor skips the fix prompt and only reports issues.

Usage with other commands:

# Run doctor before pairing
hicli doctor && hicli pair

# Run doctor after update
hicli update && hicli doctor

hicli notify

Manage notification features. Notifications are always enabled and push to Android devices via Tailscale.

hicli notify

Running hicli notify without a subcommand shows the current hook status and available commands.

Example output:

Manage hicli notification features.

Notification is always enabled and pushes to Android devices via Tailscale.
AI tool hooks are managed automatically by 'hicli doctor'.

Hook Status:
  ✓ Claude Code
  ✓ Codex
  ✓ Gemini CLI

Usage:
  hicli notify [command]

Commands:
  hook        Handle AI tool hook events (internal)
  test        Test notification delivery

notify test

Send a test notification to paired Android devices.

hicli notify test

Flags:

Examples:

# Default test
hicli notify test

# Custom message
hicli notify test --title="Build Done" --message="All tests passed"

Example output:

Sending test notification to Android devices...
  Found 2 device(s), sending...
  Remote notification sent successfully

Test complete

notify hook

Handle AI tool hook events. This command is called automatically by AI tool hooks, not by users directly.

hicli notify hook --tool=<name> --event=<event>

Flags:

How it works:

• Reads JSON from stdin (provided by the AI tool’s hook system)
• Extracts relevant information (last message, project name, etc.)
• Pushes a notification to all paired Android devices
• Outputs {} to stdout (required by hook protocol)

stdin JSON format:

The hook reads a JSON object from stdin. Fields vary by tool:

{
  "cwd": "/path/to/project",
  "hook_event_name": "Stop",
  "last_assistant_message": "The task is complete...",
  "completion_reason": "end_turn",
  "notification_type": "tool_use",
  "message": "Tool execution finished",
  "details": {
    "tool_name": "bash"
  }
}

Supported tools and events:

Manual configuration for unsupported tools:

Any tool that supports running a command on events can use hicli. The hook command format:

<hicli-path> notify hook --tool=<name> --event=<event>

Example for Cursor (.cursor/settings.json):

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "<hicli-path> notify hook --tool=cursor --event=stop"
      }]
    }],
    "Notification": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "<hicli-path> notify hook --tool=cursor --event=notification"
      }]
    }]
  }
}

Note: Replace <hicli-path> with the actual path to the hicli binary (run which hicli to find it).

hicli update

Update hicli to the latest version.

hicli update

Download sources (priority order):

1. GitHub Releases (default) — better global CDN
2. HiCloud Mirror (yinbin.ink) — fallback for mainland China

Flags:

Examples:

# Check for updates without installing
hicli update --check

# Force HiCloud mirror (for China mainland)
hicli update --source=hicloud

# Install a specific version
hicli update --version=v0.9.0

# Skip checksum verification
hicli update --skip-verify

Example output:

Current version: v0.9.0
Checking for updates...
Latest version: v1.0.0
New version available: v0.9.0 → v1.0.0
Downloading...
✓ Download complete (8.2 MB)
Verifying file integrity...
✓ Verification passed
Updating...
✓ Update successful

How the update works:

1. Checks the latest version from the primary source
2. If the primary source fails, automatically falls back to the other
3. Downloads the binary for your platform (os/arch)
4. Verifies SHA256 checksum (unless --skip-verify)
5. Replaces the current binary (old version backed up as .old)
6. Removes the backup on success

hicli uninstall

Completely uninstall hicli.

hicli uninstall

What it removes:

• Config directory (~/.hiterm/)
• AI tool notification hooks (from Claude Code, Codex, Gemini settings)

What it does NOT remove:

• The hicli binary itself (you must delete it manually)
• Tailscale or its configuration
• mosh, tmux, or sshd

Example output:

Are you sure you want to uninstall hicli? This cannot be undone. [y/N]: y
Removing notification hooks...
Deleting config files...
✓ hicli uninstalled

Note: You need to manually delete the binary:
  rm /Users/alice/.local/bin/hicli

Global Flags

# Show version
hicli --version

# Show help for any command
hicli pair --help
hicli notify --help

Configuration File

Path: ~/.hiterm/config.json Permissions: 0600 (owner read/write only)

{
  "version": "1.0",
  "pc_info": {
    "hostname": "macbook-pro",
    "platform": "darwin",
    "arch": "arm64",
    "os_version": "14.0",
    "username": "alice",
    "ssh_port": 22,
    "ssh_username": "alice"
  },
  "notify": {
    "tools": ["claude", "codex", "gemini"]
  },
  "services": {
    "systemd_enabled": false,
    "launchd_enabled": false,
    "service_name": "hicli",
    "install_path": ""
  }
}

Field descriptions:

Note: You normally don’t need to edit this file manually. hicli pair and hicli doctor manage it automatically.

See Also

• Quick Start — Get started in 3 steps
• PC Installation — Detailed install guide
• Troubleshooting — Common issues and solutions