Getting Started

This page introduces osdk's shared command surface. See Runtimes and Ecosystem Tools for backend options, Projects and Configuration for discovery, and Reproducible Lockfiles for precise read/write rules and the floating-Rust-channel exception.

Your first workflow

# Install explicit requests; prefixes select the highest matching stable version
osdk install node@20 python@3.12

# Install and write the request to this project
osdk use node@20

# Generate and commit the selected platform's resolution
osdk lock

# Recreate it on another machine of the same platform
osdk install

# Run temporarily without changing a project pin
osdk exec --tool node@20 -- node --version

Tool requests normally use TOOL@VERSION. Omitting @VERSION means latest. Common requests include exact versions (20.11.1), prefixes (20, 20.11), latest, current, stable, lts, lts/iron, and user aliases. Supported channels and ranges vary by backend.

Global options

osdk [GLOBAL OPTIONS] <COMMAND> [COMMAND OPTIONS]

Global options may appear before or after the subcommand.

Option	Environment	Effect
-v, --verbose	OSDK_LOG separately sets a tracing filter	Repeat for info, debug, then trace output
-q, --quiet	—	Hide download/install progress; it does not hide normal results or approve deletion
-j N, --jobs N	OSDK_JOBS	Maximum concurrent downloads/installations; CLI 0 does not override config, and execution uses at least 1
-y, --yes	OSDK_YES	Approve uninstall, archive-cache cleanup, and real GC
--source ID	—	Put source ID first while retaining fallbacks; tool requests must use the canonical backend ID (for example, node, not nodejs)
--refresh-sources	—	Force re-probing for install, use, upgrade, and exec; model sync refreshes only with no explicit endpoint/pin, auto selection, and online mode; no effect on lock, outdated, or list-remote
--source-mode MODE	OSDK_SOURCE_MODE	auto (default) validates a mirror set in the environment and ranks it together with the built-in mirrors; env uses only that mirror and fails when it is missing or unusable
--offline	OSDK_OFFLINE	Prohibit network access and use cached metadata/artifacts only
--require-checksums	OSDK_REQUIRE_CHECKSUMS	Reject an artifact without a normal checksum or trusted attestation digest
--attestations POLICY	OSDK_ATTESTATIONS	off, if-available, or required
--prerelease POLICY	OSDK_PRERELEASE	never, if-explicit, or allow
--lang LANG	OSDK_LANG	en or zh; affects help and argument errors too
-h, --help	—	Show help
-V, --version	—	Show the version

CLI boolean flags enable a behavior for that invocation; the same flag cannot turn a configured true back to false. For example, disable signature verification with OSDK_VERIFY_SIGNATURES=false or configuration.

Install, lock, check, and upgrade

osdk install|i [TOOL[@VERSION] ...] [-o|--opt KEY=VALUE ...] [--include-lazy]
osdk lock [TOOL[@VERSION] ...] [-o|--opt KEY=VALUE ...]
osdk outdated [TOOL[@VERSION] ...]
osdk upgrade [TOOL[@VERSION] ...] [-o|--opt KEY=VALUE ...]

Command	Behavior
install	Install tools and generate shims; a bare project install consumes the current-platform lock when present, otherwise resolves configuration and records an exact lock; lazy entries are skipped unless --include-lazy is present
lock	Resolve requests and write a platform-partitioned osdk.lock; do not install; floating Rust channels remain channel names
outdated	Re-resolve configuration or explicit requests and report targets not installed; never read the lock
upgrade	Re-resolve, install, and refresh the lock; never use the old lock as resolution input

-o/--opt is repeatable and must be KEY=VALUE. A later duplicate wins. The same option set is applied to every tool in a multi-tool command, so do not mix backend-specific options with unrelated tools.

osdk --jobs 4 install node@20 go@1.22 python@3.12
osdk install --include-lazy
osdk install rust@stable -o profile=minimal -o components=clippy,rustfmt
osdk lock node@20 -o arch=arm64
osdk outdated node@20 python@3.12
osdk upgrade

Explicit install TOOL... is a one-shot shared installation and changes neither project [tools] nor the lock. Use osdk use TOOL@VERSION to add a project selection; it installs the tool and atomically updates project configuration and the current-platform lock.

A structured [tools] entry with lazy = true stays out of a no-argument install by default. --include-lazy includes all such entries. The flag is not needed for explicit operands: naming a tool is already an explicit request to install it. Runtime dependencies of an included tool are installed even when their own declaration is lazy.

See Reproducible Lockfiles for the exact read/write matrix. Floating Rust channels such as stable, beta, and nightly are not frozen to a concrete release. Use an explicit or dated toolchain for immutable rebuilding.

Set the current version and uninstall

osdk use|u TOOL[@VERSION] [-g|--global] [-o|--opt KEY=VALUE ...]
osdk uninstall|rm TOOL@VERSION

use installs and generates shims, then writes a pin. By default it updates the nearest project configuration, creating osdk.toml in the current directory if none exists. --global updates user config.toml. An explicit prefix or channel is preserved; a bare tool stores the exact resolved version.

uninstall normally expects an exact version. A prefix selects the last string-sorted installed match; other non-exact requests are rejected. Bare rust is the exception and removes stable. It asks for confirmation, so pass --yes in automation. When a regular dynamic tool is removed, osdk also removes any user-global pin and user lock entry that still select that version; project configuration and project locks are unchanged. Newly unreferenced CAS objects are collected afterward. Shell activation fails explicitly when a configured runtime is not installed instead of silently using a same-named command from the system PATH.

Inspect local and remote versions

osdk list|ls [TOOL]
osdk list-remote|lsr TOOL [FILTER]
osdk current [TOOL]
osdk where TOOL[@VERSION]
osdk reshim

Command	Exact semantics
list [TOOL]	List local versions with completion markers; without a tool, include registered backends and inventory-backed dynamic tools found on disk, including GitHub, Cargo, and Go command tools
list-remote TOOL [FILTER]	List stable remote versions; optional FILTER is a string prefix
current [TOOL]	Show the raw request and discovery source for the current directory; the request need not be installed or remotely resolved
where TOOL[@VERSION]	With an explicit selector (including prefixes such as 21 or build-number-less 21.0.12), select only from installed versions using the same matching rules as install and error when nothing matches, without reading the project selection; a bare tool resolves the active version (project ecosystem files, config, dynamic shim request), falling back to the last installed entry
reshim	Regenerate shims for installed built-in and inventory-backed dynamic tools, and coordinate npm/npx routing

current node and where node answer different questions: the former shows the project selection (which need not be installed), while the latter prints an installed directory — a bare tool follows the active version, and an explicit where node@<selector> locates strictly among installed versions. Give a selector when a script needs a deterministic path.

Temporary execution

osdk exec (-t|--tool TOOL[@VERSION])... -- COMMAND [ARG ...]

--tool is required and repeatable. osdk installs those requests if needed, builds their exact PATH and backend environment, and starts COMMAND once. It does not read the project lock or change pins.

osdk exec --tool python@3.12 -- python -c "print('ok')"
osdk exec --tool node@20 --tool pnpm@10 -- pnpm install

pnpx routes to managed pnpm dlx; bunx routes to managed bun x. The corresponding backend must be included. Package-manager commands may also run registry preflight. Child failure makes osdk return an error; exact child exit-code pass-through is not guaranteed.

Version aliases

osdk alias set TOOL NAME TARGET
osdk alias list [TOOL]
osdk alias unset TOOL NAME

osdk alias set node maintenance 20
osdk alias set node default maintenance
osdk alias list node
osdk use node@default
osdk alias unset node maintenance

The CLI always edits user-global aliases. A project may define [alias.tools.<tool>] manually and override a global name. Alias chains are allowed; cycles are rejected. Names cannot be empty, contain whitespace or @, or use latest, current, stable, system, lts, lts/*, lts-latest, or any lts/ or lts- prefix. Tool aliases are canonicalized before storage.

This kind of alias replaces a version request only. It is expanded by install/use/uninstall, activation, shim selection, and global npm-tool version resolution; it neither renames an executable nor duplicates an installation. [alias] is a category namespace reserved for future capabilities such as alias.shell; only alias.tools exists today, and unknown categories fail explicitly.

Tool name aliases

Input	Canonical backend
nodejs	node
py, cpython	python
jdk, openjdk	java
golang	go
rustup	rust
mvn	maven
kotlinc	kotlin

Next, read Projects and Configuration to turn individual commands into a shared project environment.