Command reference
63 public CLI commands in Pinset 2.1. Each page covers syntax, state changes, JSON support, exit codes, and key errors.
Project and selection commands
7pinset initCreate a minimal project configuration in the current directory.→pinset detectRead traditional project version files and report selections, constraints, ignored tools, unsupported values, and conflicts.→pinset importRe-scan and import every safe traditional selection into schema 4 pinset.toml and schema 3 pinset.lock.→pinset globalShow global selections or batch-set any combination of global runtime defaults.→pinset useResolve and lock one or more runtimes for the nearest project, or for global scope.→pinset unsetRemove one project or global selection without uninstalling its runtime.→pinset installInstall one explicit exact runtime, or install every target from a project/global lock.→Query and lifecycle commands
12pinset whichPrint the exact executable Pinset would use for a command.→pinset currentShow the effective project, global, or system runtime selection and executable.→pinset listList installed versions, or query official available versions for one Provider.→pinset outdatedCompare each exact locked version with the newest version compatible with its requested selector and with the latest stable release.→pinset updateRe-resolve requested selectors and refresh exact lock records without changing selectors or installing runtimes.→pinset migrateValidate and rewrite schema 1–3 project configuration as schema 4 while retaining schema 3 runtime locks, without re-resolving versions.→pinset lock auditAudit one project or global configuration/lock pair, its current-platform artifacts, relevant content-addressed cache entries, install receipts, and receipt-backed ownership. Project Python selections also audit the .venv ownership marker.→pinset uninstallRemove one exact Pinset-owned runtime installation.→pinset pruneRemove installed versions not protected by global or supplied project selections.→pinset execRun a child command with Pinset's selected runtimes and environment without relying on direct shell routing.→pinset xResolve, verify, install, and run one Provider command without changing project/global selection state.→pinset doctorDiagnose the project boundary and strict policy, lockfile, installation, command routing, environment, PATH state, and traditional migration-only sources.→Download cache commands
7pinset cacheGroup download-cache inspection, verification, repair, cleanup, and offline import operations.→pinset cache listList complete content-addressed runtime archives.→pinset cache infoSummarize complete and partial download-cache usage.→pinset cache verifyHash every complete archive and compare it with its content identity.→pinset cache repairRemove corrupt complete archives so a later install can fetch them again.→pinset cache cleanRemove complete content-addressed archives from the download cache.→pinset cache importImport a reviewed archive into the verified offline cache.→Python environment commands
4pinset venvGroup project-owned Python environment operations.→pinset venv createInstall the selected CPython runtime if needed, then create or validate the project .venv.→pinset venv statusShow the selected CPython distribution and managed project-environment path.→pinset venv recreateDelete and recreate the project .venv after proving Pinset ownership.→Command-routing commands
6pinset shimGroup inspection and repair operations for Provider command routes.→pinset shim pathPrint the user-owned directory containing Pinset command shims.→pinset shim installRepair command shims without overwriting files Pinset does not own.→pinset shim migrateRegister configured Provider commands in the current routing directory while preserving existing entries.→pinset activatePrint shell code that prepends Pinset's command-routing directory to PATH.→pinset completionsGenerate Pinset completion code for a supported shell.→Source commands
7pinset sourceGroup local Provider source inspection, selection, policy, and validation operations.→pinset source listList built-in and custom sources, optionally for one Provider.→pinset source addAdd a named custom archive source, optionally granting trusted metadata authority.→pinset source useSelect the active source for one supported Provider.→pinset source fallbackReplace the ordered fallback source list for one Provider.→pinset source removeRemove an inactive custom source.→pinset source testPerform read-only connectivity and Provider metadata validation for one source.→Provider Registry commands
2Encrypted project environment commands
18pinset env initCreate one empty encrypted profile, a device age X25519 identity, and normally a separate recovery identity.→pinset env setAdd or replace one encrypted variable in a profile.→pinset env unsetRemove one variable, matching its name case-insensitively.→pinset env listList variable names in one profile without writing values to output.→pinset env revealPrint exactly one decrypted value for deliberate human inspection.→pinset env importImport an explicitly named plaintext dotenv file into one encrypted profile.→pinset env exportDeliberately export one profile as a plaintext dotenv file for a system that cannot consume Pinset injection.→pinset env recipient addAllow another age X25519 identity to decrypt one profile.→pinset env recipient removeRemove one recipient from a profile after proving current decryption access.→pinset env recipient listPrint the public recipients configured for one profile.→pinset env identity createGenerate an additional age X25519 identity and print its ID plus public recipient.→pinset env identity importRestore a passphrase-protected recovery/backup identity into this machine's system keyring.→pinset env identity listList registered identity IDs, public recipients, and storage backends without private keys.→pinset env identity backupBack up one keyring identity to a new passphrase-protected age file.→pinset env identity exportExport a keyring identity as plaintext, primarily for an explicitly protected CI secret.→pinset trust addApprove automatic environment injection for the current canonical project and its exact environment policy.→pinset trust statusCheck whether the current project and environment policy match a local trust record.→pinset trust revokeRemove this machine's automatic-injection approval for one project.→