harbor-check-cli: SSH tunnel quick start

This CLI accesses a Harbor Check service running on a remote server through an SSH tunnel. It is useful when Harbor Check listens only on 127.0.0.1:8000.

Install

python -m pip install --upgrade harbor-check-cli

You need an SSH account on the remote server, and Harbor Check must be running there on 127.0.0.1:8000.

Open an SSH tunnel

Run this locally and keep the terminal open:

ssh -N -L 8000:127.0.0.1:8000 YOUR_SERVER_USERNAME@YOUR_SERVER_HOST

If local port 8000 is busy, choose another local port and use it consistently below.

Log in through the tunnel

In a second terminal:

harbor-check login \
  --server http://127.0.0.1:8000 \
  --username YOUR_SERVER_USERNAME

Enter the password when prompted. The token is stored in ~/.config/harbor-check/credentials.json with permissions restricted to the current user.

Use the CLI

harbor-check tasks
# List currently running tasks globally
harbor-check running
# Limit the list to one username
harbor-check running --username USERNAME
# Limit it to one username and folder
harbor-check running --username USERNAME --folder FOLDER_NAME
harbor-check folders
harbor-check folder-tasks FOLDER_NAME
harbor-check task USER/FOLDER/TASK_NAME --detail
harbor-check stop USER/FOLDER/TASK_NAME
harbor-check restart USER/FOLDER/TASK_NAME

Upload a task directory through the same tunnel:

harbor-check upload ./my-task \
  --username YOUR_SERVER_USERNAME \
  --server http://127.0.0.1:8000

Put --json before the subcommand for machine-readable output:

harbor-check --json tasks
harbor-check --json running --username USERNAME

Troubleshooting

• Connection refused: the SSH tunnel is closed, the local port is wrong, or Harbor Check is not listening on 127.0.0.1:8000 on the server.
• An HTML error page: use the tunnel address http://127.0.0.1:8000, not the server's public address.
• Login failure: verify the server username and password accepted by the Harbor Check deployment.