ALLP Manager allp CLI · Wiki

ALLP Manager is a transparent orchestrator for package managers already installed on a machine. It offers one command surface without hiding where software comes from, which native command will run, or which privilege boundary is required.

Documentation map

The mental model

request → discover installed managers → query capable backends
        → show choices → build immutable native plan
        → show exact command → confirm → execute directly

ALLP Manager does not own dependency resolution or a package database. APT, Pacman, DNF, Flatpak, Snap and the other native tools remain authoritative.

Safety promise

• Package-manager commands are program-plus-argv values, not shell strings.
• A mutation is planned and displayed before it executes.
• --dry-run never performs a mutation or invokes sudo.
• --yes skips only ALLP Manager's final confirmation; it does not blindly inject confirmation flags into native tools.
• Root access is applied to the required child only. User-scoped tools remain in the original user's context when ALLP Manager was started through sudo.
• ALLP Manager collects no telemetry and stores no credentials.

Canonical engineering references

This wiki explains the product. The repository's detailed contracts remain authoritative: architecture, command semantics, backend contract, JSON schema, and security model.

Requirements

• Linux for mature package orchestration; macOS/Homebrew is experimental.
• A supported native package manager already installed.
• Rust 1.74+ only when building from source.
• sudo only when a selected native child genuinely requires root.

⚠️ Install Rust and Cargo before running make. Git, Make and a C compiler/linker are also required. Follow the official Rust installation guide, reopen your terminal, then check:

rustc --version
cargo --version

Install from source

git clone https://github.com/allp-manager/allp-manager.git
cd allp-manager
make install

make install builds ALLP Manager and uses sudo to copy it to /usr/local/bin/allp.

User installation without sudo

Choose this instead of make install to install only for your user, from the same repository directory:

make install-user
export PATH="$HOME/.local/bin:$PATH"
allp --version

The destination is ~/.local/bin/allp. The PATH command above applies to the current terminal; add that line to your shell configuration for future sessions.

Termux on Android

Termux is not currently a supported ALLP Manager environment. make install uses sudo and installs to /usr/local/bin; this does not fit a standard Termux installation. make install-user avoids sudo during installation, but does not make package operations compatible with Termux: ALLP Manager’s APT mutations still require root. Native Termux support needs separate runtime, path and privilege handling. Until that support is implemented and tested, manage Termux packages with its native pkg command.

First safe session

# 1. See platform, paths and usable backends
allp doctor
allp detect --verbose

# 2. Search without changing the host
allp search git

# 3. Inspect the exact plan
allp install git --from apt --dry-run

# 4. Run after reviewing the source, argv and privilege label
allp install git --from apt

Use --scope apps, --scope dev, or --scope all to avoid an interactive scope question. Use --from <backend> whenever source identity matters.

Update versus upgrade

update refreshes backend metadata. upgrade upgrades installed software. The exact native meaning is backend-defined and always shown first.

allp update --dry-run
allp upgrade --dry-run
allp update
allp upgrade

Never delete native lock files after a busy error; find or wait for the owning package-manager process instead.

Linux package orchestration is the primary product surface. macOS Homebrew is experimental. Windows supports compilation, diagnostics, release target selection and verified deferred self-replacement, but does not advertise Linux Snap/Flatpak backends.

ALLP Manager recognizes Debian, Red Hat/Fedora, Arch, SUSE and Alpine families, plus Bazzite as an image-based Fedora-family host. It records architecture, libc, WSL/container state and platform data directories.

⚠️ Install Rust and Cargo before running make. Git, Make and a C compiler/linker are also required. Follow the official Rust installation guide, reopen your terminal, then check:

rustc --version
cargo --version

Install from source

git clone https://github.com/allp-manager/allp-manager.git
cd allp-manager
make install

make install builds ALLP Manager and uses sudo to copy it to /usr/local/bin/allp.

User installation without sudo

Choose this instead of make install to install only for your user, from the same repository directory:

make install-user
export PATH="$HOME/.local/bin:$PATH"
allp --version

The destination is ~/.local/bin/allp. The PATH command above applies to the current terminal; add that line to your shell configuration for future sessions.

Termux on Android

Termux is not currently a supported ALLP Manager environment. make install uses sudo and installs to /usr/local/bin; this does not fit a standard Termux installation. make install-user avoids sudo during installation, but does not make package operations compatible with Termux: ALLP Manager’s APT mutations still require root. Native Termux support needs separate runtime, path and privilege handling. Until that support is implemented and tested, manage Termux packages with its native pkg command.

Verify path and identity

command -v allp
allp --version --verbose
make install-check   # in a source checkout

If the wrong copy resolves, update PATH and run hash -r (bash) or rehash (zsh). A native dpkg/rpm/Pacman-owned binary remains managed by that source.

This guide follows the way a person actually uses ALLP Manager: inspect the machine, search, choose a trustworthy source, review a plan, mutate, and verify.

1. Know your environment

allp --version --verbose
allp doctor
allp detect --verbose

doctor explains the OS, distro family, architecture/libc, user and sudo context, ALLP Manager installation ownership, data directories, release target and backend readiness. detect focuses on every built-in backend and capability. Fix FoundButUnavailable or FoundButUnconfigured before use.

2. Search in the right scope

allp search firefox --scope apps
allp search black --scope dev
allp search git --scope all
allp search pycharm --from snap

• apps: system packages, universal apps and Homebrew.
• dev: Python, Node and Rust/Cargo ecosystems.
• all: every eligible source.
• --from: one exact backend or installer such as apt, flatpak, snap, homebrew, pipx, pnpm, or cargo.

Matches are Exact, Related or Fuzzy. Use --exact for strict matching or --all for weak fuzzy results. Same names do not prove package equivalence.

3. Inspect before installation

allp info firefox
allp info firefox --from flatpak --full
allp info git --from apt --raw
allp install git --from apt --dry-run

Default info is curated, --full expands normalized metadata, and --raw shows native output. Dry run performs discovery, resolution and plan creation while executing no mutation and no sudo.

4. Install or remove

allp install git --from apt
allp install org.mozilla.firefox --from flatpak
allp install black --from pipx
allp install typescript --from pnpm
allp install ripgrep --from cargo

allp remove git --from apt --dry-run
allp remove git --from apt

Read the package ID, source, scope, exact native argv and privilege label. If a source is ambiguous, choose it explicitly; --yes does not choose for you. Prerequisite installation or remote addition is a separate plan.

5. Inspect installed software

allp list
allp list --from apt --filter git
allp list --from flatpak --limit 50 --no-pager
allp list --json

Filtering happens before limiting. Long interactive output uses a directly spawned pager, not a hidden shell pipeline.

6. Maintain the machine

allp update --dry-run
allp upgrade --dry-run
allp update
allp upgrade

Update refreshes metadata; upgrade changes installed software. Plans are built for the whole batch before confirmation, then run sequentially and continue after individual failures. Exit code 8 means partial failure.

allp update --from apt --skip-self-update
allp upgrade --from flatpak
allp update --scope dev --target tools --dry-run
allp upgrade --scope dev --target global --dry-run
allp update --no-tui

7. Reproduce a toolset

allp profile save workstation
allp profile export workstation workstation.toml
# review the TOML on the destination
allp profile import workstation.toml --name new-machine
allp profile install new-machine --dry-run
allp profile install new-machine

Profiles preserve backend identity. Versions are inventory observations, not pins, and system inventories may include dependencies.

8. Use in CI or scripts

allp search git --from apt --json
allp update --dry-run --json
allp install git --from apt --no-interactive --yes

Require the expected JSON schema_version, inspect complete and issues, and handle documented exit codes. Real mutation should follow a reviewed dry run. Unattended prerequisite bootstrap additionally needs --allow-bootstrap.

Recommended habits

1. Run ALLP Manager as your normal user, not with blanket sudo allp.
2. Use --from for reproducibility and security-sensitive installs.
3. Dry-run unfamiliar backends and maintenance batches.
4. Keep native package-manager locks intact.
5. Verify registry ownership; do not trust a familiar package name alone.

Canonical syntax is allp <command> [arguments] [options]. Add -v (repeatable) for diagnostics. Common output flags are --json, --no-color, and --no-tui.

Search and source selection

allp search ripgrep --exact
allp search editor --all --limit 50
allp search black --scope dev
allp search pycharm --from snap

The default human view contains exact and bounded related results. --all includes weak fuzzy matches. Noninteractive/JSON requests default to the apps scope unless --scope or --from is explicit.

Mutations

allp install org.mozilla.firefox --from flatpak --dry-run
allp install black --from pipx --no-interactive --yes
allp remove ripgrep --from cargo --dry-run

Important mutation flags:

• --dry-run: plan and validate but do not execute.
• --no-interactive: never display a selector or prompt.
• --yes: bypass only the final ALLP Manager confirmation after choices are resolved.
• --allow-bootstrap: permit a separately planned prerequisite when combined with --yes in unattended use.

Maintenance

allp update --skip-self-update
allp update --self-only
allp update --check-only
allp update --offline
allp update --scope dev --target tools --dry-run
allp upgrade --scope dev --target all --dry-run
allp upgrade --allow-stale-metadata  # explicit recovery only

Developer targets are project, workspace, global, environment, tools, and all. Unsupported target/backend combinations are reported, never guessed.

Inventory and information

allp list --from apt --filter openssl --limit 20 --no-pager
allp info firefox --from flatpak
allp info git --full
allp info git --from apt --raw

--raw asks the backend for native output. --full expands normalized fields.

Stable exit codes

See the canonical command contract for backend-specific maintenance semantics.

ALLP Manager searches capable backends concurrently in bounded groups. Each parser returns candidates plus structured issues; unknown non-empty native output is unrecognized_output, not a fabricated no-match.

Scope selection prunes eligible backends before execution. A backend outside the selected scope is not invoked merely to filter its results afterward; this avoids unrelated work, while the actual speed depends on the active sources and machine.

Ranking

1. Exact package/display-name matches.
2. Related matches, capped per backend and selected round-robin.
3. Fuzzy matches, hidden unless --all is used.

allp search git --exact
allp search editor --limit 10
allp search editor --all --limit 50

Cross-backend identity is descriptive. Verified canonical mappings may form a group; probable relationships are labeled uncertain; same-name results remain separate. ALLP Manager never chooses a meaningful source automatically.

Interactive controls

For large result sets, Space/b moves pages, / filters, a number chooses the global result, Enter accepts the highlighted/first visible item, and q or Escape cancels. Filtering never renumbers the original global choices.

Noninteractive rule

Scripts cannot answer scope or source questions. Provide them explicitly:

allp search git --scope apps --json
allp install git --from apt --dry-run --no-interactive
allp install git --from apt --no-interactive --yes

If multiple choices remain, exit code 4 is returned with recovery guidance.

ALLP Manager discovers backends on every invocation and advertises only capabilities that are actually available. “Experimental” means implemented and fake-PATH tested, but still needing broader real-host validation.

System backends

APT refreshes metadata with apt-get update and upgrades with its native upgrade plan. Pacman intentionally has no standalone update capability because partial upgrades are unsafe; upgrade uses a full sync-and-upgrade plan. DNF supports DNF4 and DNF5 output shapes.

On Bazzite, DNF host mutation is disabled even if a helper exists. rpm-ostree handles metadata refresh, image upgrades and explicit package layering. A layered change normally requires reboot and is presented as a last resort after Flatpak, Homebrew or containers.

Flatpak

ALLP Manager distinguishes “missing executable”, “installed with no remotes”, “ready”, and “probe failed”. Flathub addition is a separate, user-scoped bootstrap plan.

allp doctor flatpak
allp search firefox --from flatpak
allp install org.mozilla.firefox --from flatpak --dry-run

Snap

Snap prefers the local snapd REST socket for wide discovery, exact resolution, installation and terminal change monitoring. Before planning it validates the canonical name, publisher, confinement, architecture, channel and installed state. An authoritative snap-not-found response never falls back to stale CLI metadata. CLI fallback is restricted to transport or compatibility failures.

allp doctor snap
allp install pycharm --from snap --dry-run

Classic confinement adds --classic only when metadata requires it.

Homebrew

One validated locator is shared by detect, doctor and operations. It checks configured paths, revalidated state, original-user paths and official prefixes. Under sudo allp, Homebrew still runs as its validated owner.

allp doctor homebrew --verbose --no-color
sudo allp update --from homebrew --dry-run --skip-self-update

Python, Node and Rust

Registry names are not assumed to be official. Fuzzy registry matches cannot be installed automatically. User/project scopes are preserved and are never silently elevated.

allp install black --from pipx --dry-run
allp install typescript --from pnpm --dry-run
allp install ripgrep --from cargo --dry-run

Cargo host maintenance never calls cargo add or project cargo update. Global binary upgrades require the optional community cargo-update command.

The exact operation matrix is maintained in CAPABILITY_MATRIX.md.

ALLP Manager plans every selected backend before executing a maintenance batch. APT metadata refresh is a dependency of APT upgrade; failure defers that upgrade unless the user explicitly accepts stale metadata.

allp update --dry-run
allp upgrade --dry-run
allp upgrade --allow-stale-metadata  # recovery only

Backends define semantics: APT/DNF refresh metadata, Pacman combines sync and upgrade, Flatpak/Snap refresh installed apps, Homebrew separates metadata and package upgrade, and rpm-ostree stages transactional changes.

Self-update controls

allp self-update --check-only
allp self-update --update-channel stable
allp self-update --update-channel continuous
allp self-update --update-channel prerelease
allp update --skip-self-update
allp update --self-only
allp update --offline

Fresh installs default to stable. Explicit channel choices persist. Offline contacts neither GitHub nor package sources. A newer local build is never downgraded and is reported as LocalAhead.

Official assets are selected by OS, architecture, libc and target from a signed identity chain of manifest metadata and SHA-256 evidence. Replacement keeps a rollback backup until the new binary passes verification. Successful allp update replacement re-executes once and continues backend maintenance without looping.

Profiles are experimental, versioned TOML inventories that preserve both the package ID and owning backend.

allp profile save workstation
allp profile list
allp profile show workstation
allp profile export workstation workstation.toml
allp profile import workstation.toml --name laptop
allp profile install laptop --dry-run
allp profile install laptop

version = 1
name = "developer-tools"

[[packages]]
backend = "apt"
package = "git"

[[packages]]
backend = "rust"
package = "ripgrep"
version = "14.1.1"

Version is observed inventory metadata, not a pin. ALLP Manager does not translate an APT package into a DNF package. Before applying, every backend is verified so a missing backend cannot stop the run after earlier packages already changed the host. Installation then uses the normal per-package search, planning and confirmation path.

System inventory can include dependencies. Review the exported file before moving it to another machine. Imports reject unknown fields, duplicate entries, unsafe names, unsupported profile versions and excessive sizes. Writes are atomic and use a rollback file when replacing an existing profile.

On Linux, profiles normally live under ~/.config/allp/profiles/; confirm the effective platform-specific path with allp doctor.

Installation limits in v0.6.4

Recorded package versions are inventory observations, not version pins: installation uses the backend’s currently available version. Profile installation confirms each package and stops at the first failed operation; packages installed earlier remain installed. It does not automatically resume only failed entries. Review the completed operations and edit a separate retry profile if needed before running again.

Use explicit scopes and backends in unattended code. JSON is supported for read-only commands and maintenance dry runs; human prompts, colors and spinners are never mixed into JSON stdout.

allp detect --json
allp search git --from apt --json
allp list --from flatpak --json
allp info git --from apt --json
allp update --dry-run --json
allp upgrade --dry-run --json

Envelope

{
  "schema_version": 2,
  "command": "search",
  "complete": true,
  "results": {
    "query": "git",
    "effective_scope": "apps_and_tools",
    "candidates": [],
    "groups": [],
    "backends": []
  },
  "issues": []
}

Treat schema_version as the compatibility boundary and complete as a data quality signal. complete: false can coexist with useful candidates when one backend returned partial or unrecognized output; inspect issues before acting.

Safe shell example

report="$(mktemp)"
if allp search git --from apt --json >"$report"; then
  jq -e '.schema_version == 2 and .complete == true' "$report" >/dev/null
  jq '.results.candidates[] | {backend_id, package_id, match_kind}' "$report"
fi
rm -f "$report"

For mutation automation, first archive a dry-run report, then use a fully resolved backend/package with --no-interactive --yes. Never assume that --yes approves source selection or prerequisite bootstrap.

allp install git --from apt --dry-run
allp install git --from apt --no-interactive --yes

Bootstrap additionally requires --allow-bootstrap. Exit code 8 means a multi-backend batch partially failed; do not treat it as total success.

See JSON_SCHEMA.md for every field.

ALLP Manager follows platform data-directory conventions. On Linux the effective paths normally resolve under ~/.config/allp, ~/.local/state/allp, and ~/.cache/allp. Never assume a path in automation; read allp doctor because platform and environment can change it.

Profiles are in the config directory's profiles/*.toml. State writes are atomic. Homebrew locator records are revalidated before use; a stale executable path is rejected and discovery continues.

allp doctor prints effective paths, executable ownership/writability, current and original users, and release target without dumping unrelated environment variables or tokens.

Environment variables prefixed ALLP_TEST_ and internal continuation variables are implementation/test boundaries, not public configuration. Prefer documented CLI flags and profiles for user-facing behavior.

Real interactive update and upgrade runs can show an inline APT-style progress footer. Native stdout/stderr remains normal scrollback; the footer shows percentage when detectable, active backend/action, elapsed time and queue completion. It is an observer and cannot change planned argv or privilege.

allp update
allp upgrade
allp update --no-tui     # classic streaming
allp update --no-color   # layout without ANSI color

The live view is disabled for JSON, dry-run, redirected/non-TTY output, TERM=dumb, and --no-interactive. Terminal control sequences from untrusted native output are sanitized before UI projection. Width fitting prevents the footer from wrapping into prompts.

When root children are planned, sudo authentication completes before the live renderer starts. Credential expiry suspends/clears the footer and revalidates outside it; failure is classified as a blocked operation.

ALLP Manager is a Rust 2021 application organized around domain models, backend capabilities and immutable execution plans.

CLI
 └─ App bootstrap
    ├─ PlatformContext + RuntimePrivilegeContext
    ├─ CapabilityRegistry + RequirementSet
    ├─ Detector → DetectedBackendSet
    └─ Operation → Backend query/plan → Renderer → ProcessRunner

Self-update
 └─ trusted GitHub source → manifest → staged verification
    → platform replacement → post-check/rollback → guarded continuation

Module responsibilities

Architectural invariants

1. Discovery is fresh on every invocation.
2. Generic operations select by capability, not hard-coded backend ID.
3. Native flags and parsers stay inside backend modules.
4. Mutating backend methods return ExecutionPlan; they do not spawn.
5. The runner uses std::process::Command with a separate executable and argument vector for native package operations. The exception is the official Homebrew bootstrap: a separately confirmed, visible /bin/bash -c plan downloads the vendor installer to a temporary file and runs it with /bin/bash. It does not pipe a download into a shell and does not currently verify a pinned installer checksum.
6. Multiple meaningful sources require a user decision.
7. Unknown parser output is not converted into a false “no results”.

Search pipeline

Backends are queried with bounded concurrency. Results are normalized into Exact, Related and Fuzzy matches. Exact results are always visible; related results are selected round-robin across backends; fuzzy results require --all. Verified identity groups, probable relationships and same-name coincidences remain visibly distinct.

Adding a backend

A backend implements the contract in src/backends/contract.rs, declares requirements and capabilities, owns all native parsing/planning, is registered once in src/backends/catalog.rs, and adds fixtures plus tests. Run:

make quality
bash scripts/check-architecture.sh

See ARCHITECTURE.md and ADDING_BACKEND.md for the normative rules.

ALLP Manager coordinates tools that may change an operating system. Its primary safety property is a visible plan with a narrow execution boundary—not a claim that third-party packages are trustworthy.

Command and privilege boundary

• The runner uses std::process::Command with a separate executable and argument vector for native package operations. The exception is the official Homebrew bootstrap: a separately confirmed, visible /bin/bash -c plan downloads the vendor installer to a temporary file and runs it with /bin/bash. It does not pipe a download into a shell and does not currently verify a pinned installer checksum.
• Package IDs beginning with - are rejected before mutation.
• Root-required executables and their parent directories are canonicalized and checked for root ownership and unsafe write permissions.
• Normal use starts as a user. Only the required child is wrapped with sudo --.
• Maintenance validates once with sudo -v, then uses sudo -n -- so a password prompt cannot corrupt the live UI.
• User-scoped Homebrew, Python, Node, Cargo and Flatpak work is de-escalated to the validated original sudo user. Direct-root user-scoped work is refused if no original user can be established.

Confirmation model

allp install git --from apt --dry-run  # zero mutation, zero sudo
allp install git --from apt            # plan → confirmation → execution
allp install git --from apt --yes      # only skips Allp's final confirmation

Bootstrap is a separate mutation. Unattended bootstrap requires both --yes and --allow-bootstrap after its exact plan is printed.

Registry and output trust

Package-manager output is untrusted data. Python, Node and Rust registry names are not treated as official, and fuzzy matches are not auto-installed. Cargo build scripts or installer hooks may execute during a real native install, but never during ALLP Manager dry-run.

Self-update trust chain

ALLP Manager accepts only its compiled official repository identity. HTTPS requests are bounded. Manifest identity, target, archive name, size and SHA-256 are checked; unsafe paths and links are rejected. The staged binary's build identity and bytes are rechecked across helper boundaries. Replacement retains a rollback backup until post-install verification succeeds. A dpkg/rpm/Pacman-owned ALLP Manager binary is handed back to its native package source and is not overwritten.

Privacy and reporting

ALLP Manager has no telemetry, daemon, stored sudo password or credential store. Report command injection, privilege escalation, unsafe resolution, credential leakage or misleading JSON through the repository's private security advisory channel, not a public issue.

The alpha is not security-audited. Read SECURITY.md and the normative security model before production use.

Local setup

git clone https://github.com/allp-manager/allp-manager.git
cd allp-manager
rustup show
cargo build
cargo run -- detect

The minimum supported Rust version is 1.74; rust-toolchain.toml tracks stable with rustfmt and Clippy.

Quality gate

make fmt-check
make check
make clippy
make test
make architecture
make release
make docs-check
make quality       # all of the above

Tests use fake executables and captured fixtures. Never run destructive native package operations in a test. Parser changes require representative fixture output. Behavior changes require an Unreleased changelog entry, a regression test and an updated guardrail.

Backend change checklist

1. Declare identity, category, requirements and precise capabilities.
2. Keep native argv and parsing inside the backend module.
3. Return immutable plans for mutations; never spawn from a backend.
4. Define scope and privilege behavior.
5. Add success, no-match, malformed-output and failure fixtures.
6. Register once in src/backends/catalog.rs.
7. Run make quality.

CI

The repository runs the Linux quality gate, portable tests on Linux/macOS/ Windows, Linux cross-target checks, family bootstrap contracts, and a weekly native backend canary. Release jobs build target-specific archives, checksums and a manifest.

Local release

make hooks-install
make release-prepare BUMP=patch
make release-status
# commit with: release: Allp vX.Y.Z
make release-push

Preparation updates versioned files and runs the quality gate. The guarded post-commit hook creates only an annotated local tag and ignored dist/ artifacts. Nothing is pushed or published until make release-push is called.

Read CONTRIBUTING.md, REGRESSION_GUARDRAILS.md, and the release documentation before submitting changes.

Start with read-only evidence:

allp --version --verbose
allp doctor
allp detect --verbose
allp detect --json >allp-detect.json

For APT stale metadata after a failed refresh, fix the underlying problem and retry. --allow-stale-metadata is an explicit recovery override, not a normal operating mode.

When filing a bug, include the exact command, distro/tool versions, expected behavior, actual native output, and sanitized allp detect --json. Do not post credentials or vulnerability details publicly.

Is ALLP Manager another package manager? No. It orchestrates installed native tools and owns neither dependency resolution nor a universal package database.

Does it hide native commands? No. Mutating argv, source, scope and privilege are shown before confirmation.

Should I run sudo allp? Normally no. Run as a user and let the central runner elevate only root-required children.

Are update and upgrade the same? No. Semantics are backend-defined; typically update refreshes metadata and upgrade changes installed software.

Does --yes approve everything? No. It skips only final ALLP Manager confirmation. Ambiguous sources and bootstrap remain explicit.

Can profiles reproduce exact versions? Not yet. Version 1 records observed versions but does not pin them.

Does ALLP Manager modify project lockfiles? Host Cargo maintenance never does. Python/Node project actions require explicit target/scope and remain cautious.

Is it production hardened? It is public alpha and not security-audited.

How does ALLP Manager compare with Topgrade?

Topgrade focuses on detecting installed tools and running their update commands; it also supports custom commands. ALLP Manager adds a package discovery and selection workflow: search across eligible sources, inspect a package, choose a backend explicitly and review the native installation plan. Choose based on the workflow you need; native package managers remain responsible for packages in both cases.