.\" Man page for coral(1)
.\" Copyright (C) 2025 Leafscale, LLC
.TH CORAL 1 "January 2026" "Coral 0.2.2" "Zygaena Package Manager"

.SH NAME
coral \- package manager for Zygaena

.SH SYNOPSIS
.B coral
.RI [ options ]
.I command
.RI [ arguments ]

.SH DESCRIPTION
.B 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.

.SH COMMANDS

.SS "Package Operations"

.TP
.BI "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/.

.TP
.BI "install " "package ..."
Install one or more packages. Packages can be specified as:
.RS
.IP \(bu 2
Package name (downloaded from repository or built locally)
.IP \(bu 2
Path to a .pkg.tar.xz file
.IP \(bu 2
Group name prefixed with @ (e.g., @base-devel)
.RE

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

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

.SS "Query Operations"

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

.TP
.B list
List all installed packages with their versions.

.TP
.BI "files " package
List all files owned by an installed package.

.TP
.BI "owner " file
Find which package owns a given file path.

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

.TP
.BI "depends " package
Display the dependency tree for a package.

.TP
.B diff
Show packages that have newer versions available.

.SS "Repository Operations"

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

.TP
.BI "repo " subcommand
Manage package repositories. Subcommands:
.RS
.TP
.B list
List configured repositories
.TP
.B refresh
Refresh repository metadata
.TP
.BI "add " "name url"
Add a new repository
.TP
.BI "remove " name
Remove a repository
.TP
.BI "init " path
Initialize a new repository structure
.TP
.BI "rebuild " path
Rebuild repository manifest from packages
.TP
.BI "sign " path
Sign repository manifest
.TP
.BI "verify " path
Verify repository signature
.RE

.SS "Key Management"

.TP
.BI "key " subcommand
Manage signing keys. Subcommands:
.RS
.TP
.B list
List keys in the keyring
.TP
.BI "generate " name
Generate a new Ed25519 signing key
.TP
.BI "import " "file name"
Import a public key
.TP
.BI "export " name
Export a public key
.TP
.BI "trust " name
Add key to trusted keys
.TP
.BI "revoke " name
Remove key from trusted keys
.TP
.B init
Initialize the keyring directory
.RE

.SS "Cache Management"

.TP
.BI "cache " subcommand
Manage package caches. Subcommands:
.RS
.TP
.B clean
Remove cached packages
.TP
.B clean-sources
Remove cached source archives
.TP
.B clean-all
Remove all cached data
.TP
.B stats
Show cache statistics
.RE

.SS "Database Management"

.TP
.BI "db " subcommand
Manage the package database indexes. The database provides fast O(log N) lookups
for file ownership and package information. Subcommands:
.RS
.TP
.B init
Initialize the database indexes. Creates packages.db and files.db in
/var/lib/coral/db/. Run this once during initial system setup.
.TP
.B 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.
.TP
.B status
Display database status including number of indexed packages and files.
.TP
.B dump
Display the contents of the files index (for debugging).
.RE

.SH OPTIONS

.TP
.BR \-h ", " \-\-help
Display help message and exit.

.TP
.B \-\-version
Display version information and exit.

.TP
.BR \-y ", " \-\-yes
Assume yes to all prompts. Do not ask for confirmation.

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

.TP
.BR \-v ", " \-\-verbose
Enable verbose output. Show additional details during operations.

.TP
.BR \-n ", " \-\-dry\-run
Show what would be done without making changes.

.TP
.BR \-q ", " \-\-quiet
Minimal output. Only show errors.

.TP
.B \-\-no\-color
Disable colored output.

.TP
.BI \-\-root " path"
Use an alternative root directory for installation.

.SH FILES

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

.SH CONFIGURATION
The configuration file /etc/coral/coral.conf uses TOML format:

.nf
[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
.fi

.SH EXAMPLES

Build and install a package:
.nf
    coral build vim
    coral install vim
.fi

Install multiple packages:
.nf
    coral install vim nano htop
.fi

Install a package group:
.nf
    coral install @base-devel
.fi

Search for packages:
.nf
    coral search editor
.fi

Show package dependencies:
.nf
    coral depends vim
.fi

Find which package owns a file:
.nf
    coral owner /usr/bin/vim
.fi

Upgrade all packages:
.nf
    coral upgrade
.fi

Generate a signing key:
.nf
    coral key generate mykey
.fi

Sign a repository:
.nf
    coral repo sign /path/to/repo
.fi

Initialize the package database:
.nf
    coral db init
.fi

Check database status:
.nf
    coral db status
.fi

Rebuild database indexes (if corrupted):
.nf
    coral db rebuild
.fi

.SH EXIT STATUS
.TP
.B 0
Success.
.TP
.B 1
General error.
.TP
.B 2
Command line usage error.
.TP
.B 3
Package not found.
.TP
.B 4
Dependency resolution failed.
.TP
.B 5
Build failed.
.TP
.B 6
Permission denied (not root).

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

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

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

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