Last updated: 2026-05-25

Command Reference

hiterm pair

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

hiterm 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 Hi Term 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 Hi Term!

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: hiterm 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 hiterm pair to try again.

hiterm login

Login to HiTerm to unlock advanced features.

hiterm login

Why Login?

Logging in is a one-time operation that unlocks two critical features:

  1. Remote Notifications: Receive real-time updates on your phone when AI tools (Claude Code, etc.) complete long-running tasks.
  2. Identity Auto-Sync: Automatically pushes your PC's identity (Hostname, IP, SSH Username) to your phone.

How it works:

  • Runs a local callback server.
  • Opens your system browser for OAuth authentication (GitHub, Google, or Gitee).
  • Saves an auth token locally in ~/.hiterm/config.json.
  • No Expiration: Once logged in, you remain logged in unless you explicitly run hiterm logout.

hiterm logout

Sign out and disable remote notifications.

hiterm logout

hiterm doctor

Diagnose and auto-fix common configuration issues. Also provides a System Overview including your Tailscale status and paired device list.

hiterm doctor
Check What it verifies Auto-fixable
Tailscale Running and logged in No
Config ~/.hiterm/config.json permissions (0600) Yes
SSH Service sshd is listening on configured port No
mosh mosh binary is installed Yes (auto-install)
Notifications AI tool hooks are properly configured Yes

Example output:

hiterm 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]

hiterm notify

Manage notification features and test delivery.

hiterm notify

Auto-Sync Feature (The "Magic" Sync)

HiTerm features a unique P2P Identity Push mechanism. When you are logged in, every notification sent to your phone carries your PC's current Tailscale IP and configuration.

How it works automatically:

  • You do not need to do anything special.
  • When your PC's IP changes (e.g., changing network), simply continue working with your AI tools.
  • The next time the tool sends a notification (e.g., task completion), your phone receives it and silently updates the IP in your host list automatically.

Manual Sync (Optional): If you want to force a synchronization immediately without waiting for an AI event, you can run:

hiterm notify test

notify test

Send a test notification to paired Android devices. This is the fastest way to trigger an Auto-Sync.

hiterm notify test

Flags:

Flag Description Default
--title Notification title "Hi Term Test Notification"
--message Notification message "This is a test notification message"

Examples:

# Default test
hiterm notify test

# Custom message
hiterm 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 (Internal)

Handle AI tool hook events. This command is called automatically by AI tool hooks. It extracts the Project Name from the working directory to provide contextual notifications like [my-app] Task complete.

hiterm update

Update hiterm to the latest version.

hiterm update

Download sources (priority order):

  1. GitHub Releases (default) โ€” better global CDN
  2. Hono Mirror (yinbin.ink) โ€” fallback for mainland China

Flags:

Flag Description Default
--check Only check for new version, don't install false
--source Primary download source: github or hono github
--version Install a specific version (GitHub only) (latest)
--skip-verify Skip SHA256 checksum verification false

hiterm uninstall

Completely uninstall hiterm.

hiterm uninstall

What it removes:

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

Global Flags

Flag Short Description
--help -h Show help information
--version -v Show version information 
# Show version
hiterm --version

# Show help for any command
hiterm pair --help
hiterm 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"]
  }
}

See Also