Beltic logo
CLI Guide

CLI Installation

Install and set up the Beltic CLI for credential management and verification.

The Beltic CLI manages agent manifests, generates cryptographic fingerprints, and signs/verifies credentials from the terminal.

Quick Install

Homebrew (macOS/Linux)

brew tap belticlabs/tap
brew install beltic

Shell Script (macOS/Linux)

curl -fsSL https://raw.githubusercontent.com/belticlabs/beltic-cli/master/install.sh | sh

After installation, add to your PATH:

export PATH="$PATH:$HOME/.beltic/bin"

Add this line to your shell profile (~/.bashrc, ~/.zshrc, etc.) for persistence.

Build from Source

Prerequisites

  • Rust 1.70+ (Rust 2021 edition)
  • Git for cloning the repository

Install Rust

If you don't have Rust installed:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
rustc --version  # Verify installation

Step 1: Clone the Repository

git clone https://github.com/belticlabs/beltic-cli.git
cd beltic-cli

Step 2: Build Release Binary

cargo build --release

Build time: 2-5 minutes depending on your system

Output: Binary at ./target/release/beltic

Step 3: Verify Installation

./target/release/beltic --version
./target/release/beltic --help

Expected output:

beltic 0.1.0
Beltic credential management CLI

USAGE:
    beltic <SUBCOMMAND>

SUBCOMMANDS:
    init          Initialize agent manifest
    dev-init      Create self-attested developer credential
    fingerprint   Generate code fingerprint
    keygen        Generate cryptographic keypair
    sign          Sign credential as JWS
    verify        Verify JWS signature
    http-sign     Sign HTTP requests (Web Bot Auth)
    directory     Key directory management
    help          Print help information

Installation Options

Option 1: Add to PATH (Temporary)

export PATH=$PATH:$(pwd)/target/release
beltic --version  # Works from any directory

Note: This only lasts for your current terminal session.

Option 2: Add to PATH (Permanent)

Add to your shell profile (~/.bashrc, ~/.zshrc, or ~/.profile):

export PATH=$PATH:/path/to/beltic-cli/target/release

Then reload:

source ~/.zshrc  # or ~/.bashrc

Option 3: Install Globally with Cargo

cd beltic-cli
cargo install --path .

Binary location: ~/.cargo/bin/beltic

Benefit: Automatically in PATH if Cargo bin directory is configured

ln -s $(pwd)/target/release/beltic /usr/local/bin/beltic
beltic --version

Requires: sudo permissions on some systems

Verify Installation

Run a simple command to confirm:

beltic keygen --help

Expected: Help text for the keygen command

Platform Support

The CLI has been tested on:

  • macOS: 11+ (Intel and Apple Silicon)
  • Linux: Ubuntu 20.04+, Debian 11+, Fedora 35+
  • Windows: Windows 10+ (via WSL or native)

Windows Notes

Option 1: WSL (Recommended)

wsl --install
# Then follow Linux installation steps

Option 2: Native Windows

  • Install Rust via rustup.rs
  • Use cargo build --release in PowerShell or Command Prompt
  • Binary will be at target\release\beltic.exe

Update CLI

If installed via Homebrew:

brew upgrade beltic

If installed via shell script:

curl -fsSL https://raw.githubusercontent.com/belticlabs/beltic-cli/master/install.sh | sh

If built from source:

cd beltic-cli
git pull origin master
cargo build --release

Note: If you used cargo install, re-run:

cargo install --path . --force

Uninstall

If installed via Homebrew:

brew uninstall beltic
brew untap belticlabs/tap

If installed via shell script:

rm -rf ~/.beltic

If installed via cargo:

cargo uninstall beltic

If built from source:

rm -rf beltic-cli  # Remove entire directory

If symlinked:

rm /usr/local/bin/beltic

Troubleshooting

Issue: "cargo: command not found"

Cause: Rust not installed or not in PATH

Solution:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Issue: "linker 'cc' not found"

Cause: C compiler not installed

Solution (Ubuntu/Debian):

sudo apt-get install build-essential

Solution (macOS):

xcode-select --install

Solution (Fedora):

sudo dnf install gcc

Issue: Build fails with "failed to verify checksum"

Cause: Corrupted dependency cache

Solution:

cargo clean
cargo build --release

Next Steps

Creating Your First Credential

End-to-end tutorial for credential creation

Command Reference

Complete command documentation

Managing Fingerprints

Init and fingerprint workflows

Beltic CLI

Manage manifests, fingerprints, signing, and verification from the terminal

Workflows

Step-by-step guides for common CLI workflows including credential creation, signing, and fingerprint management.

On this page

Quick InstallHomebrew (macOS/Linux)Shell Script (macOS/Linux)Build from SourcePrerequisitesInstall RustStep 1: Clone the RepositoryStep 2: Build Release BinaryStep 3: Verify InstallationInstallation OptionsOption 1: Add to PATH (Temporary)Option 2: Add to PATH (Permanent)Option 3: Install Globally with CargoOption 4: Symlink to User BinariesVerify InstallationPlatform SupportWindows NotesUpdate CLIIf installed via Homebrew:If installed via shell script:If built from source:UninstallIf installed via Homebrew:If installed via shell script:If installed via cargo:If built from source:If symlinked:TroubleshootingIssue: "cargo: command not found"Issue: "linker 'cc' not found"Issue: Build fails with "failed to verify checksum"Next Steps