goharbor/harbor-cli

README

Harbor CLI — a command-line interface for interacting with your Harbor container registry. A streamlined, user-friendly alternative to the WebUI, as your daily driver or for scripting and automation.

Scope 🧪

CLI alternative to the WebUI
Tool for scripting and automation of common repeatable Harbor tasks running on your machine or inside your pipeline

Features

The project's first goal is to reach WebUI parity.

✅ project       Manage projects  
✅ repo          Manage repositories  
✅ artifact      Manage artifacts  
✅ label         Manage labels  
✅ tag           Manage tags   
✅ quota         Manage quotas  
✅ webhook       Manage webhook policies 
✅ robot         Robot Account 

✅ login         Log in to Harbor registry  
✅ user          Manage users  

✅ registry      Manage registries
✅ replication   Manage replication

✅ config        Manage the config of the Harbor CLI
✅ cve-allowlist Manage system CVE allowlist
✅ health        Get the health status of Harbor components
✅ preheat       Manage preheat provider instances
✅ info          Display detailed Harbor system, statistics, and CLI environment information

✅ Scanner       scanner commands CRUD
✅ schedule      Schedule jobs in Harbor

✅ vulnerability List and view vulnerability summary from Harbor Security Hub

❌ Distribution

❌ GC

❌ Job Service   Dashboard

❌ Auditlog      Auditlogs dashboard

✅ completion    Generate the autocompletion script for the specified shell
✅ help          Help about any command
✅ version       Version of Harbor CLI

Install

For additional artifacts like archives, checksums and SBOMs, refer to the releases page.

Container

Running Harbor CLI as a container is simple. Use the following command to get started:

docker run -ti --rm -v $HOME/.config/harbor-cli:/root/.config/harbor-cli \
  -e HARBOR_ENCRYPTION_KEY=$(echo "ThisIsAVeryLongPassword" | base64) \
  registry.goharbor.io/harbor-cli/harbor-cli \
  --help

Use the HARBOR_ENCRYPTION_KEY container environment variable as a base64-encoded 32-byte key for AES-256 encryption. This securely stores your harbor login password.

If you intend to run the CLI as a container, it is advised to set the following environment variables and to create an alias and append the alias to your .zshrc or .bashrc file

echo "export HARBOR_CLI_CONFIG=\$HOME/.config/harbor-cli" >> ~/.zshrc
echo "export HARBOR_ENCRYPTION_KEY=\$(cat <path_to_32bit_private_key_file> | base64)" >> ~/.zshrc
echo "alias harbor='docker run -ti --rm -v \$HARBOR_CLI_CONFIG:/root/.config/harbor-cli -e HARBOR_ENCRYPTION_KEY=\$HARBOR_ENCRYPTION_KEY registry.goharbor.io/harbor-cli/harbor-cli'" >> ~/.zshrc 
source ~/.zshrc # or restart your terminal

Homebrew(Linux/macOS)

brew install harbor-cli

Debian/Ubuntu(.deb)

Replace <version> with the desired release version (e.g., v0.x.x).

wget https://github.com/goharbor/harbor-cli/releases/download/<version>/harbor-cli_<version>_linux_amd64.deb
sudo dpkg -i harbor-cli_<version>_linux_amd64.deb

Fedora/CentOS(.rpm)

wget https://github.com/goharbor/harbor-cli/releases/download/<version>/harbor-cli_<version>_linux_amd64.rpm
sudo rpm -i harbor-cli_<version>_linux_amd64.rpm

Alpine(.apk)

wget https://github.com/goharbor/harbor-cli/releases/download/<version>/harbor-cli_<version>_linux_amd64.apk
sudo apk add --allow-untrusted harbor-cli_<version>_linux_amd64.apk

APT

echo "deb [trusted=yes] https://harborcli.goharbor.io stable main" | sudo tee /etc/apt/sources.list.d/harbor-cli.list
sudo apt update
sudo apt install harbor-cli

Add the Harbor CLI to your Container Image

Using Curl or Wget isn't needed if you want to add the Harbor CLI to your container. Instead, we recommend copying the Harbor CLI from our official image by using the following Dockerfile:

#...
COPY --from=registry.goharbor.io/harbor-cli/harbor-cli:latest /harbor /usr/local/bin/harbor
# --chown and --chmod flags can be used to set the permissions

Example Commands💡

>./harbor    

Official Harbor CLI

Usage:
  harbor [command]

Examples:

// Base command:
harbor

// Display help about the command:
harbor help


Available Commands:
  artifact      Manage artifacts
  completion    Generate the autocompletion script for the specified shell
  config        Manage the config of the Harbor CLI
  cve-allowlist Manage system CVE allowlist
  health        Get the health status of Harbor components
  help          Help about any command
  info          Show the current credential information
  instance      Manage preheat provider instances in Harbor
  label         Manage labels in Harbor
  login         Log in to Harbor registry
  project       Manage projects and assign resources to them
  registry      Manage registries
  repo          Manage repositories
  schedule      Schedule jobs in Harbor
  tag           Manage tags in Harbor registry
  user          Manage users
  version       Version of Harbor CLI

Flags:
  -c, --config string          config file (default is $HOME/.config/harbor-cli/config.yaml)
  -h, --help                   help for harbor
  -o, --output-format string   Output format. One of: json|yaml
  -v, --verbose                verbose output

Use "harbor [command] --help" for more information about a command.

Config Management

Hierarchy

Use the --config flag to specify a custom configuration file path (the highest priority).

  harbor --config /path/to/custom/config.yaml artifact list

If --config is not provided, Harbor CLI checks the HARBOR_CLI_CONFIG environment variable for the config file path.

export HARBOR_CLI_CONFIG=/path/to/custom/config.yaml
harbor artifact list

If neither is set, it defaults to $XDG_CONFIG_HOME/harbor-cli/config.yaml or $HOME/.config/harbor-cli/config.yaml if XDG_CONFIG_HOME is unset.

harbor artifact list

Data Path

Data paths are determined by the XDG_DATA_HOME environment variable.
If XDG_DATA_HOME is not set, it defaults to $HOME/.local/share/harbor-cli/data.yaml.
The data file always contains the path of the latest config used.

Config TL;DR

--config flag > HARBOR_CLI_CONFIG environment variable > default XDG config paths.
Environment variables override default settings, and the --config flag takes precedence over both environment variables and defaults.
The data file always contains the path of the latest config used.

Log in to Harbor Registry

harbor login demo.goharbor.io -u harbor-cli -p Harbor12345

Create a New Project

harbor project create

List all Projects

harbor project list

# output
┌──────────────────────────────────────────────────────────────────────────────────────────┐
│  Project Name  Access Level  Type          Repo Count    Creation Time                   │
│ ──────────────────────────────────────────────────────────────────────────────────────── │
│  library       public        project       0             1 hour ago                      │
└──────────────────────────────────────────────────────────────────────────────────────────┘

List all Repository in a Project

harbor repo list

# output
┌────────────────────────────────────────────────────────────────────────────────────────┐
│  Name                      Artifacts     Pulls         Last Modified Time              │
│ ────────────────────────────────────────────────────────────────────────────────────── │
│  library/harbor-cli        1             0             0 minute ago                    │
└────────────────────────────────────────────────────────────────────────────────────────┘

Supported Platforms

Platform	Status
Linux	✅
macOS	✅
Windows	✅

Build From Source

Make sure you have the latest Dagger installed in your system.

Using Dagger

git clone https://github.com/goharbor/harbor-cli.git && cd harbor-cli
dagger call build-dev --platform darwin/arm64 export --path=./harbor-cli
./harbor-dev --help

If golang is installed in your system, you can also build the project using the following commands:

git clone https://github.com/goharbor/harbor-cli.git && cd harbor-cli
go build -o harbor-cli cmd/harbor/main.go

Version Compatibility With Harbor

At the moment, the Harbor CLI is developed and tested with Harbor 2.13. The CLI should work with versions prior to 2.13, but not all functionalities may be available or work as expected.

Harbor <2.0.0 is not supported.

Community

Twitter: @project_harbor
User Group: Join Harbor user email group: harbor-users@lists.cncf.io to get update of Harbor's news, features, releases, or to provide suggestion and feedback.
Developer Group: Join Harbor developer group: harbor-dev@lists.cncf.io for discussion on Harbor development and contribution.
Slack: Join Harbor's community for discussion and ask questions: Cloud Native Computing Foundation, channel: #harbor-cli.
Community Calls: Every Tuesday at 15:00 CET/CEST or 18:30 IST - Join Meeting. View Meeting Notes for details.

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Acknowledgements

This project is maintained by the Harbor community. We thank all our contributors and users for their support.

❤️ Show your support

For any questions or issues, please open an issue on our GitHub Issues page.
Give a ⭐ if this project helped you, Thank YOU!