Sigil Auth
beginner clilinuxinstallationdebianubuntufedoraarchalpine

Installing on Linux

Complete installation guide for Sigil Auth CLI device on Linux distributions

Installing Sigil Auth on Linux

Complete installation guide for Sigil Auth CLI device (sigil-device) on Linux distributions.

Quick Install

Ubuntu / Debian

# Download and install .deb package
curl -LO https://github.com/sigilauth/cli-device/releases/latest/download/sigil-device_0.1.0_linux_amd64.deb
sudo dpkg -i sigil-device_0.1.0_linux_amd64.deb

# Verify installation
sigil-device --version

Fedora / RHEL / Rocky Linux

# Download and install .rpm package
sudo dnf install https://github.com/sigilauth/cli-device/releases/latest/download/sigil-device-0.1.0-1.x86_64.rpm

# Verify installation
sigil-device --version

Arch Linux

# Via AUR helper (recommended)
yay -S sigil-device

# Or manual AUR build
git clone https://aur.archlinux.org/sigil-device.git
cd sigil-device
makepkg -si

Alpine Linux

# Download and install .apk package
curl -LO https://github.com/sigilauth/cli-device/releases/latest/download/sigil-device_0.1.0_linux_amd64.apk
sudo apk add --allow-untrusted sigil-device_0.1.0_linux_amd64.apk

# Verify installation
sigil-device --version

Any Linux (Binary Tarball)

# Download tarball
curl -LO https://github.com/sigilauth/cli-device/releases/latest/download/sigil-device_0.1.0_linux_amd64.tar.gz

# Extract
tar -xzf sigil-device_0.1.0_linux_amd64.tar.gz

# Install (system-wide)
sudo install -m 755 sigil-device /usr/local/bin/

# Or install (user-local)
mkdir -p ~/.local/bin
install -m 755 sigil-device ~/.local/bin/
# Add ~/.local/bin to PATH if not already there

# Verify
sigil-device --version

Package Signature Verification

TODO: GPG signature verification steps pending Sigil Auth release key publication.

Once available:

# Import Sigil Auth release key
curl https://sigilauth.com/release-key.asc | gpg --import

# Verify package signature
gpg --verify sigil-device_0.1.0_checksums.txt.sig sigil-device_0.1.0_checksums.txt
sha256sum --check sigil-device_0.1.0_checksums.txt

Repository Installation (Future)

TODO: Package repository hosting not yet configured. Manual package installation required for v0.1.0.

Planned for v0.2.0:

  • apt repository for Debian/Ubuntu
  • dnf repository for Fedora/RHEL/Rocky
  • Flathub for universal Flatpak distribution

First Run

After installation, initialize your device identity:

# Generate device keypair (stored in ~/.sigil-device/)
sigil-device init

# Pair with your Sigil server
sigil-device pair --server https://sigil.example.com:8443

# Register for push notifications
sigil-device register --relay https://relay.sigilauth.com

# Listen for authentication requests
sigil-device listen --relay https://relay.sigilauth.com

See man sigil-device for detailed command documentation.

Running as a Service

Enable persistent background listener via systemd:

# Enable service (starts on login)
systemctl --user enable sigil-device.service

# Start service now
systemctl --user start sigil-device.service

# Check status
systemctl --user status sigil-device.service

# View logs
journalctl --user -u sigil-device -f

The service runs sigil-device listen --auto-approve and automatically restarts on failure.

Note: Run init, pair, and register commands manually before enabling the service.

Shell Completion

Tab completion is automatically enabled after package installation for bash, zsh, and fish.

Restart your shell or source the completion file:

# Bash
source /usr/share/bash-completion/completions/sigil-device

# Zsh
autoload -Uz compinit && compinit

# Fish (auto-loaded on next shell start)

Troubleshooting

Command not found

Symptom: sigil-device: command not found after installation

Solutions:

  • Tarball install: Ensure /usr/local/bin or ~/.local/bin is in your $PATH
    echo $PATH
# Should include /usr/local/bin or ~/.local/bin
  • Package install: Verify package is installed:
    # Debian/Ubuntu
dpkg -l | grep sigil-device

# Fedora/RHEL
rpm -qa | grep sigil-device

# Arch
pacman -Q sigil-device

Permission denied accessing ~/.sigil-device/

Symptom: Error: Permission denied (os error 13) when running commands

Solution: Files created with wrong ownership. Reset permissions:

sudo chown -R $USER:$USER ~/.sigil-device
chmod 700 ~/.sigil-device
chmod 600 ~/.sigil-device/*.json ~/.sigil-device/*.txt

No D-Bus session

Symptom: Error: Cannot connect to D-Bus session bus

Solution: Ensure D-Bus session is running (required for desktop integration):

# Check D-Bus session
echo $DBUS_SESSION_BUS_ADDRESS

# If empty, start via systemd (if available)
systemctl --user start dbus.service

Workaround: CLI device does not strictly require D-Bus. This warning can be ignored for server/headless use.

libsecret not found (future)

Symptom: error while loading shared libraries: libsecret-1.so.0

Solution: Install libsecret (required for desktop app, not CLI):

# Debian/Ubuntu
sudo apt install libsecret-1-0

# Fedora/RHEL
sudo dnf install libsecret

# Arch
sudo pacman -S libsecret

Systemd service fails to start

Symptom: systemctl --user status sigil-device shows “failed” status

Diagnosis:

# View detailed logs
journalctl --user -u sigil-device -n 50

# Common causes:
# 1. Device not initialized: run `sigil-device init` first
# 2. Missing config: run `pair` and `register` before enabling service
# 3. Relay unreachable: check network connectivity

WebSocket connection refused

Symptom: Error: Connection refused when running listen command

Solutions:

  • Verify relay URL is correct and reachable:
    curl -I https://relay.sigilauth.com/health
  • Check firewall allows outbound WebSocket (port 443)
  • Ensure device is registered with relay:
    sigil-device register --relay https://relay.sigilauth.com

Tab completion not working

Symptom: <TAB> key doesn’t complete sigil-device commands

Solutions:

  • Bash: Ensure bash-completion package installed:
    # Debian/Ubuntu
sudo apt install bash-completion

# Fedora/RHEL
sudo dnf install bash-completion
  • Restart shell: Completions load on shell startup
    exec bash  # or exec zsh, exec fish

Man page not found

Symptom: man sigil-device shows “No manual entry”

Solution:

Uninstallation

Ubuntu / Debian

sudo apt remove sigil-device
# Or completely purge including config
sudo apt purge sigil-device

Fedora / RHEL / Rocky

sudo dnf remove sigil-device

Arch Linux

sudo pacman -R sigil-device
# Or with dependencies
sudo pacman -Rs sigil-device

Alpine

sudo apk del sigil-device

Manual / Tarball

# Remove binary
sudo rm /usr/local/bin/sigil-device

# Remove user data (optional)
rm -rf ~/.sigil-device

ARM Support

ARM64 packages are available for all distros:

# Ubuntu/Debian ARM64
curl -LO https://github.com/sigilauth/cli-device/releases/latest/download/sigil-device_0.1.0_linux_arm64.deb

# Fedora/Rocky ARM64
sudo dnf install https://github.com/sigilauth/cli-device/releases/latest/download/sigil-device-0.1.0-1.aarch64.rpm

# Alpine ARM64
curl -LO https://github.com/sigilauth/cli-device/releases/latest/download/sigil-device_0.1.0_linux_arm64.apk

# Arch ARM64
curl -LO https://github.com/sigilauth/cli-device/releases/latest/download/sigil-device-0.1.0-1-aarch64.pkg.tar.zst

# Tarball ARM64
curl -LO https://github.com/sigilauth/cli-device/releases/latest/download/sigil-device_0.1.0_linux_arm64.tar.gz

Further Reading

Getting Help

License

Sigil Auth CLI Device is licensed under AGPL-3.0-or-later.
API specifications are licensed under Apache-2.0.

See https://github.com/sigilauth/cli-device/blob/main/LICENSE