#Getting Started

A3S Use is the AI Native Package Manager for A3S. It resolves and manages native capabilities and versioned cognitive-package graphs containing Tool, MCP, OKF, A3S Flow, Skill, and UI surfaces.

#What exists on main

Only the current preview contract line is accepted: manifest v3, catalog v3, receipt v6, plan v4, host protocol v6, managed scope v2, manager tools v5, pending graph v4, pre-lock resolution attempt/diagnostic v1, pre-plan download attempt/diagnostic v1, and enablement state/operation v3. Superseded preview state is rejected with cleanup and reinstall guidance.

#Install the A3S CLI

The A3S CLI has cross-platform installers independent of the A3S Use product status. On macOS and glibc Linux, run:

curl --proto '=https' --tlsv1.2 -LsSf \
  https://raw.githubusercontent.com/A3S-Lab/a3s/main/install.sh | sh

On Windows PowerShell 5.1 or newer, run:

irm https://raw.githubusercontent.com/A3S-Lab/a3s/main/install.ps1 | iex

The scripts select the current platform archive from the official stable A3S-Lab/CLI Release, verify SHA-256, and atomically replace a user-scoped installation. They do not edit shell profiles or the user PATH by default.

After installing the CLI, explicitly install and inspect the Use development preview carried by that CLI Release:

a3s install use --source release
a3s use doctor --json

#Install the standalone Use preview

The standalone Use release installer is separate from the root a3s CLI installer above. Download it before execution so you can inspect the script. It requires Cosign, authenticates the release checksum against the exact tag workflow identity and GitHub OIDC issuer, and publishes the command only after signature, SHA-256, and extraction checks pass. The managed command also binds the packaged OCR models, OCR Skills, and Browser Skills without replacing explicit environment overrides.

Linux or macOS:

curl --proto '=https' --tlsv1.2 -fsSLo /tmp/a3s-use-install.sh \
  https://raw.githubusercontent.com/A3S-Lab/Use/main/install.sh
sh /tmp/a3s-use-install.sh

Windows x86_64 with Windows PowerShell 5.1 or PowerShell 7:

$installer = Join-Path $env:TEMP 'a3s-use-install.ps1'
Invoke-WebRequest https://raw.githubusercontent.com/A3S-Lab/Use/main/install.ps1 -OutFile $installer
& $installer

Install cosign on PATH, or select a trusted executable with --cosign on Unix and -CosignPath on Windows.

This is still a development-preview distribution path. Tagged releases add deterministic archive serialization, per-platform SPDX SBOMs, GitHub OIDC provenance/SBOM attestations, and a keyless Sigstore checksum bundle. The installer fails closed unless Cosign verifies that bundle before downloading the platform archive, then retains the verified manifest and bundle with the installed version. A second cache-free clean runner must also byte-match every shipped native executable before attested reproducibility evidence is published. The tagged v0.3.2 attempt failed that gate on four targets. The non-publishing qualification run 33651777660 passed all five targets from exact main commit 4f6e4725205d06ab81f8ea98bfee85c7eb4b2bcd and remains historical evidence. The v0.3.5 publication attempt created no Release because the public core crate was stale. Release workflow 33675697857 passed all 13 jobs for tag v0.3.6 at exact main commit 54758910f2f4ad9498137410e0a2207d412e99a1 and published the development-preview v0.3.6 Release, including the verified archives and typed crates. See Trust & Security for the remaining bootstrap boundary and optional GitHub attestation verification. Release workflow 33687297386 then passed all 13 jobs for tag v0.3.7 at exact main commit 48a0b76f8a4a87a11d16627c7bd7567920852508 and published the current development-preview v0.3.7 Release, including the verified archives and typed crates (a3s-use-core 0.2.6, a3s-use-extension 0.3.7, and a3s-use 0.3.7). See Trust & Security for the remaining bootstrap boundary and optional GitHub attestation verification. Release workflow 33720485826 then passed all 13 jobs for tag v0.3.8 at exact main commit 6d3a7baf32ce998a2e487c40fbf78b4a6cda2579 and published the current development-preview v0.3.8 Release, including the verified archives and typed crates (a3s-use-core 0.2.7, a3s-use-extension 0.3.8, and a3s-use 0.3.8). See Trust & Security for the remaining bootstrap boundary and optional GitHub attestation verification. Release workflow 33756618837 then passed all 13 jobs for tag v0.3.9 at exact main commit a5f3cc40bfb0a1021ca150d2ce4295409b74d220 and published the current development-preview v0.3.9 Release, including 19 verified release assets and typed crates (a3s-use-core 0.2.7, a3s-use-extension 0.3.9, and a3s-use 0.3.9). See Trust & Security for the remaining bootstrap boundary and optional GitHub attestation verification. Release workflow 33791616307 then passed all 13 jobs for tag v0.3.10 at exact main commit c4c80a223bfff3698ca4b4598e7175c6e3303239 and published the current development-preview v0.3.10 Release, including 19 verified release assets and typed crates (a3s-use-core 0.2.8, a3s-use-extension 0.3.10, and a3s-use 0.3.10). See Trust & Security for the remaining bootstrap boundary and optional GitHub attestation verification. Release workflow 33830280138 then passed the validation, five-target primary-build, typed-crate, and five-target independent-rebuild gates for tag v0.3.11 at exact main commit c25028ae0245ba1d28f7e2837e2a87f7e9f6fe40 and published the current development-preview v0.3.11 Release, including 19 verified release assets and typed crates (a3s-use-core 0.2.9, a3s-use-extension 0.3.11, and a3s-use 0.3.11). See Trust & Security for the remaining bootstrap boundary and optional GitHub attestation verification.

#Build from source

Rust 1.85 or newer is required:

git clone https://github.com/A3S-Lab/Use.git
cd Use
cargo build --workspace --bins --locked
./target/debug/a3s-use doctor \
  --scope-kind user --scope-id user/current --json
./target/debug/a3s-use capability snapshot \
  --scope-kind user --scope-id user/current --json

Run the repository gates from the Use checkout:

cargo fmt --all -- --check
cargo test --workspace --all-targets --locked
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings

#Exercise the development CLI

#Expose the shared manager over standard MCP

The standalone manager endpoint uses the same typed PluginManagerService as the CLI and TUI. It speaks standard MCP framing on stdout, so do not pass --json to this command:

a3s-use mcp serve manager \
  --scope-kind user \
  --scope-id user/current \
  --offline

manager, package-manager, and use/package-manager are equivalent target names. The endpoint is the privileged management plane; an arbitrary agent must receive only the capabilities authorized by a separate Capability Gateway when that embedding API is enabled.

Embedders can use CapabilityGatewayMcpServer with an injected CapabilityGatewayInvocationProvider. The server accepts an immutable, path-free catalog, publishes only its Tool descriptors, and dispatches through standard MCP; opaque invocation references stay server-side. The host may call serve_streamable_http to expose the same server at /mcp, with an explicit bearer token, optional exact browser Origin, and bounded in-flight plus rolling window admission. Native clients can omit Origin; a configured Origin is checked only when a browser Origin is supplied. The HTTP helper does not provide TLS, so bind to loopback or place it behind a trusted TLS terminator. The embedding API now includes CapabilityGatewayInvocationResolver and CapabilityGatewayResolvedProvider: a host resolves one opaque reference to a private lease, verifies the exact descriptor identity, authorizes once, and retains that lease through invocation. HTTP also supports a bounded immutable 64-entry token-to-principal registry with duplicate-token rejection and a complete credential scan. Production receipt/Runtime/Grant composition and CLI wiring remain roadmap work.

An embedding host can build that catalog from one immutable CapabilityRegistrySnapshot with CapabilityRegistrySnapshot::capability_gateway_catalog; exact package, publication, selected-surface, and readiness evidence is checked before CapabilityGatewayMcpServer::from_registry_snapshot retains its RAII lease. The host still owns signature verification and opaque-reference resolution.

The standalone CLI first persists the host-selected Registry trust boundary, then resolves a signed package and its complete SemVer dependency closure from the same enabled source set:

a3s-use registry source add packages \
  --url https://packages.example.org/a3s/ \
  --trust-root sha256:<64-hex-digits> \
  --json

a3s-use install acme/research \
  --scope-kind user \
  --scope-id user/current \
  --registry-name packages \
  --version 2.0.0 \
  --json

a3s-use upgrade acme/research \
  --scope-kind user \
  --scope-id user/current \
  --registry-name packages \
  --json

a3s-use uninstall acme/research \
  --scope-kind user --scope-id user/current --json

Use the one-to-one Plugin Manager surface when plan review and mutation must be separate. plan-* commands return the complete typed Host plan without changing package state. Copy the exact operationId and planDigest from that output; apply reopens only that durable pair and accepts confirmation only with explicit --yes:

a3s-use plugin search research --kind tool \
  --scope-kind user --scope-id user/current --json
a3s-use plugin inspect acme/research --version 2.0.0 \
  --scope-kind user --scope-id user/current --json
a3s-use plugin plan-install acme/research \
  --scope-kind user \
  --scope-id user/current \
  --registry-name packages \
  --version-requirement 2.0.0 \
  --surface tool/research \
  --json
a3s-use plugin apply-plan \
  --scope-kind user \
  --scope-id user/current \
  --operation-id <operation-id> \
  --plan-digest sha256:<64-hex-digits> \
  --yes \
  --json
a3s-use plugin plan-disable acme/research \
  --scope-kind user --scope-id user/current --json

Search, inspection, planning, exact apply, and replay support verified-cache operation where applicable; apply itself performs no Registry request. An MCP agent call never implies user confirmation, and a CLI call without --yes does not create it either.

When an exact install, upgrade, or uninstall graph remains retained, an enable/disable apply has durably admitted its active operation, or a Host has reviewed but not admitted its newest enablement plan, inspect the path-free operation evidence without contacting the Registry or mutating recovery state:

a3s-use extension diagnose acme/research \
  --scope-kind user --scope-id user/current --json
a3s-use extension diagnose acme/research --history \
  --scope-kind user --scope-id user/current --json

Select a Workspace installation with --scope-kind workspace --scope-id <id>. The command reports the reviewed plan, Registry/TUF and cutover state, provider readiness, Grant phase, lifecycle publication/drain/rollback evidence, and stable recovery guidance. It excludes paths, Registry URLs, idempotency keys, credentials, secrets, package content, and arbitrary package-authored text. Graph diagnostics cover planned, admitted, and cancelled operations. Enablement diagnostics prefer active Use evidence; otherwise a digest-bound index projects the newest Host-reviewed plan as planned or exact cancelled, without exposing Host/request/fence identity. Completed Use or Host outcomes suppress stale plans. Retained Registry-backed install/upgrade graphs and durable pre-plan download attempts report independent expected/retained archive and signed executable-planning-target bytes plus exact target missing/partial/complete state from historical provenance without network I/O, writes, or paths. An attempt survives process exit and is removed only after the reviewed graph is durable; targets and partials remain observation only, never authority. Before an exact lock exists, a durable pre-lock attempt exposes refreshed/cached Registry/TUF progress, per-source verification state and digests, role versions, bounded failures, and terminal lock evidence. It survives resolver failure or process exit and hands off to the download attempt without an intentional diagnostic gap. It excludes URLs, paths, raw transport errors, credentials, and metadata bytes. --history returns the newest 16 completed or rolled-back operations and cancelled graph plans within 8 MiB for the explicit scope/package, including the full path-free diagnostic and a separately validated terminal outcome. History is written before recovery authority is removed, exact replay deduplicates (operationId, planDigest), and the inventory remains available after uninstall. Damaged, linked, or oversized history fails closed without exposing its bytes or path. Real killed-process and Host/CLI tests prove exact planning-target resume, zero-side-effect planned/cancelled enablement projection, and stale-plan suppression during Host finalization.

Add --package-lock-digest sha256:<64-hex-digits> when applying a separately reviewed resolution. Lock drift fails before archive download. Source replacement/default/enable/disable/removal requires the exact revision from registry source list --json and --yes; identity-bound TUF/cache state and installed provenance are retained. These Registry values are illustrative; the project does not advertise a public production Registry.

Search an exact promoted OKF projection with citations:

a3s-use knowledge search "retrieval policy" --limit 5 \
  --scope-kind user --scope-id user/current --json
a3s-use knowledge audit \
  --scope-kind user --scope-id user/current --json
a3s-use knowledge backup ./user.a3s-okf-backup \
  --scope-kind user --scope-id user/current --json
a3s-use knowledge verify-backup ./user.a3s-okf-backup \
  --scope-kind user --scope-id user/current --json
a3s-use knowledge backup-retention ./backups \
  --scope-kind user --scope-id user/current --json
a3s-use knowledge plan-restore ./user.a3s-okf-backup \
  --scope-kind user --scope-id user/current --json
a3s-use knowledge restore ./user.a3s-okf-backup \
  --scope-kind user --scope-id user/current \
  --plan-digest sha256:<reviewed-plan-digest> --yes --json
a3s-use knowledge restore-status \
  --scope-kind user --scope-id user/current --json
a3s-use state backup ./use-state.a3s-use-state-backup \
  --scope-kind user --scope-id user/current --json
a3s-use state verify-backup ./use-state.a3s-use-state-backup \
  --scope-kind user --scope-id user/current --json
a3s-use state backup-retention ./backups \
  --scope-kind user --scope-id user/current \
  --max-backups 32 --max-bytes 2199023255552 --json
a3s-use state plan-restore ./use-state.a3s-use-state-backup \
  --scope-kind user --scope-id user/current --json
a3s-use state restore ./use-state.a3s-use-state-backup \
  --scope-kind user --scope-id user/current \
  --rollback-backup ./pre-restore.a3s-use-state-backup \
  --plan-digest sha256:<reviewed-plan-digest> --yes --json
a3s-use state restore-status \
  --scope-kind user --scope-id user/current --json

Backup verification detects corruption but does not recreate package, Registry, lifecycle, or Grant authority. Standalone restore validates those independent authorities, requires the current binding set to be an exact subset of the backup inventory, binds that state plus live main/WAL/SHM evidence in a path-free plan, and requires the reviewed digest at confirmed apply. It may create missing exact binding files but never overwrites conflicts or newer evidence. Broader authority recovery, clean-machine recovery, other state families, and whole-product disaster recovery remain release gates. restore-status reports the global active phase and bounded path-free history and capacity for the requested scope without rotating or rewriting evidence.

The separate state backup command captures every allowlisted Registry, generation, Grant, binding, lifecycle/package-operation, Knowledge, enablement, Host Manager, and Flow Runtime control-state family under one exclusive maintenance fence. Global expanded-package artifacts are not copied. Its deterministic a3s.use.state-backup.v2 manifest uses only portable relative paths and exact length/SHA-256/mode, family-accounting, Registry, and installed-receipt evidence. Creation rejects active or partial work, links/reparse points, special files, unknown families, and non-portable paths, then rescans before non-overwriting publication. verify-backup checks the canonical manifest, exact archive length, and every payload offline without extraction or local Use state. backup-retention fully verifies each managed archive under one external-directory lock, returns a path-free oldest-first canonical plan, requires its unchanged digest plus explicit confirmation, and preserves at least two verified generations. plan-restore then requires the exact current Use version, OS, architecture, and independently retained Registry/receipt/Grant authority before producing a path-free Add/Replace/Remove/Retain plan. Confirmed restore captures or verifies a separate external rollback archive, stages link/reparse-safe candidates, and converges a seven-phase journal across 15 tested process-exit boundaries. restore-status reports bounded active/history/capacity evidence without writes. The raw archive is sensitive integrity evidence, not a signature or missing-authority recovery mechanism; clean-machine recovery, cross-platform operational drills, and disaster-recovery exercises remain release gates.

Runtime Service, HTTP MCP, Flow, Knowledge, Skill, and UI readiness always depends on an explicit embedding-host owner. Missing ownership fails closed; Use does not substitute a permissive runner or source-only binding.

#What still blocks a supported standalone installer

The preview installer and signed release evidence exist, but a supported product installer still requires independent clean rebuild comparison for the complete staged tree/final archive under an externally operated witness, evidence retention outside GitHub Release, the complete cross-platform recovery matrix, and the remaining product operations. The preview component carried by the CLI does not replace those gates.

#Next steps

• Understand the cognitive-package model
• Package workflows with A3S Flow
• Design OKF knowledge packages
• Configure Registry trust and authorization
• Inspect ownership across Use and its hosts
• Track release blockers