CORAL(1)

NAME
coral - package manager for Zygaena

SYNOPSIS
coral [options] command [arguments]

DESCRIPTION
coral is a ports-based package manager for Zygaena (illumos). It can build packages from source ports, install binary packages from repositories, manage dependencies, and handle package signing and verification.

COMMANDS

  Package Operations

build port
    Build a package from a port. The port name should match a directory under /usr/ports/<category>/<port>. The resulting package is stored in /var/lib/coral/packages/.

install package ...
    Install one or more packages. Packages can be specified as:

    •   Package name (downloaded from repository or built locally)

    •   Path to a .pkg.tar.xz file

    •   Group name prefixed with @ (e.g., @base-devel)

remove package ...
    Remove one or more installed packages. Runs pre-remove and post-remove scripts if present.

upgrade [package ...]
    Upgrade installed packages to newer versions. If no packages are specified, upgrades all packages with available updates.

  Query Operations

info package
    Display detailed information about a package, including version, description, dependencies, and installation status.

list
    List all installed packages with their versions.

files package
    List all files owned by an installed package.

owner file
    Find which package owns a given file path.

search term
    Search for packages matching the given term in ports and repositories.

depends package
    Display the dependency tree for a package.

diff
    Show packages that have newer versions available.

  Repository Operations

sync
    Synchronize the local ports tree with the remote repository (git pull).

repo subcommand
    Manage package repositories. Subcommands:

    list
        List configured repositories

    refresh
        Refresh repository metadata

    add name url
        Add a new repository

    remove name
        Remove a repository

    init path
        Initialize a new repository structure

    rebuild path
        Rebuild repository manifest from packages

    sign path
        Sign repository manifest

    verify path
        Verify repository signature

  Key Management

key subcommand
    Manage signing keys. Subcommands:

    list
        List keys in the keyring

    generate name
        Generate a new Ed25519 signing key

    import file name
        Import a public key

    export name
        Export a public key

    trust name
        Add key to trusted keys

    revoke name
        Remove key from trusted keys

    init
        Initialize the keyring directory

  Cache Management

cache subcommand
    Manage package caches. Subcommands:

    clean
        Remove cached packages

    clean-sources
        Remove cached source archives

    clean-all
        Remove all cached data

    stats
        Show cache statistics

  Database Management

db subcommand
    Manage the package database indexes. The database provides fast O(log N) lookups for file ownership and package information. Subcommands:

    init
        Initialize the database indexes. Creates packages.db and files.db in /var/lib/coral/db/. Run this once during initial system setup.

    rebuild
        Rebuild indexes from the installed package database. The source of truth is always /var/lib/coral/installed/; indexes can be safely rebuilt at any time. Use this if indexes become corrupted or out of sync.

    status
        Display database status including number of indexed packages and files.

    dump
        Display the contents of the files index (for debugging).

OPTIONS

-h, --help
    Display help message and exit.

--version
    Display version information and exit.

-y, --yes
    Assume yes to all prompts. Do not ask for confirmation.

-f, --force
    Force operation. For install, reinstalls even if already installed. For remove, removes even with dependents.

-v, --verbose
    Enable verbose output. Show additional details during operations.

-n, --dry-run
    Show what would be done without making changes.

-q, --quiet
    Minimal output. Only show errors.

--no-color
    Disable colored output.

--root path
    Use an alternative root directory for installation.

FILES

/etc/coral/coral.conf
    Main configuration file.

/etc/coral/repos.d/
    Repository configuration files (*.repo).

/etc/coral/keys/
    Signing keys (private and public).

/usr/ports/
    Ports tree containing package build definitions.

/usr/ports/groups/
    Package group definitions (*.toml).

/var/lib/coral/installed/
    Database of installed packages (source of truth).

/var/lib/coral/db/
    Package database indexes for fast lookups.

/var/lib/coral/db/packages.db
    MsgPack index of installed package metadata.

/var/lib/coral/db/files.db
    MsgPack index mapping files to their owning packages (enables O(log N) lookups).

/var/lib/coral/packages/
    Cached binary packages.

/var/lib/coral/sources/
    Cached source archives.

/var/lib/coral/repos/
    Cached repository manifests.

/var/lib/coral/trusted-keys/
    Trusted public keys for verification.

/var/tmp/coral/work/
    Build work directory.

/var/tmp/coral/pkg/
    Package staging directory.

CONFIGURATION
The configuration file /etc/coral/coral.conf uses TOML format:
[general]
arch = "x86_64"
jobs = 0              # 0 = auto-detect
confirm = true
color = true
[paths]
ports = "/usr/ports"
packages = "/var/lib/coral/packages"
[build]
cflags = "-O2 -pipe"
strip = true
[security]
require_signed_repos = false
require_signed_packages = false

EXAMPLES
Build and install a package:
    coral build vim
    coral install vim
Install multiple packages:
    coral install vim nano htop
Install a package group:
    coral install @base-devel
Search for packages:
    coral search editor
Show package dependencies:
    coral depends vim
Find which package owns a file:
    coral owner /usr/bin/vim
Upgrade all packages:
    coral upgrade
Generate a signing key:
    coral key generate mykey
Sign a repository:
    coral repo sign /path/to/repo
Initialize the package database:
    coral db init
Check database status:
    coral db status
Rebuild database indexes (if corrupted):
    coral db rebuild

EXIT STATUS

0   Success.

1   General error.

2   Command line usage error.

3   Package not found.

4   Dependency resolution failed.

5   Build failed.

6   Permission denied (not root).

SEE ALSO
coral.conf(5), coral-build(7), coral-repo(7)

BUGS
Report bugs at https://github.com/leafscale/zygaena/issues

AUTHORS
Chris Tusa <chris.tusa@leafscale.com>
Leafscale, LLC - https://www.leafscale.com

COPYRIGHT
Copyright (C) 2025 Leafscale, LLC. Licensed under BSD-2-Clause.