Version: v5.6.1

opschain academy install

packs:academy

opschain academy install [--academy-server <url>] [--grant-file <file>] [--version <x.y.z>] [--channel stable|preview] [--force]
opschain academy install --from <archive-or-binary> [--force]

Installs the OpsChain Academy agent. By default the agent is resolved through the Academy Server's release catalogue: the server answers with a signed catalogue document naming the newest installable version on the channel this build follows (stable, or the exact --version you ask for) and the SHA-256 of its archive per platform; the launcher verifies the document's Ed25519 signature against the server's signing key (the key this build pins when it carries one), downloads the archive for this platform with your Academy credential, verifies the bytes against the catalogue's digest — a mismatch installs nothing — and extracts the agent binary to <opschain home>/academy/bin/academy-opschain-agent, with an installed.json beside it recording the version, the digest, the server, the channel, the SDK version the catalogue named and the id of the key that signed it. With --from the agent is installed from a file you hold instead (the offline lane). See opschain docs packs-academy, "How the agent is installed".

The credential. Every download is identified; the server serves an agent only to an organisation entitled to it (every organisation holds the OpsChain agent). Three credential classes are accepted, in this order of lookup:

--grant-file <file> or ACADEMY_AGENT_GRANT_FILE — the registration grant (art_…) LimePoint issued your organisation, the same file academy serve --grant-file reads at first start. Downloading never consumes it.
OPSCHAIN_ACADEMY_RELEASE_TOKEN — a registration grant, an installed agent's deployment token (at_…, the upgrade path) or a learner token (lt_…, the learner-local lane).

Without one the command refuses by name. The value is never printed; the notice on stderr names only where it came from (grant-file or environment).

Versions. --version 0.2.0 installs that exact version. A version its publisher yanked is withheld from the channel's newest and from any unpinned install, but still served to a caller pinning it by exact version (rollback, reproducibility). The build's pinned release (opschain academy show) is the floor the server lane accepts: a catalogue offering only older versions is refused by name; a newer stable is never stopped. Installing the version that is already installed is a no-op unless --force is given.

--from — the offline lane. Takes either of two files:

The release archive for your platform — academy-opschain-agent_<version>_<os>_<arch>.tar.gz (.zip on Windows). Its SHA-256 is verified against the digest this build pins for the platform before anything is written. A build that pins no release cannot verify an archive, refuses by name, and takes the binary form.
A built agent binary — a development build, or a copy carried onto an air-gapped machine. Installed as it is, recorded as version local with its digest and path.

--from is a file lane and nothing else: it takes no server, channel or version flag.

Flag	Meaning
`--academy-server <url>`	Academy Server to resolve the agent through (default the one this build pins; `ACADEMY_AGENT_SERVER`)
`--grant-file <file>`	file holding the registration grant to download with (`ACADEMY_AGENT_GRANT_FILE`); `OPSCHAIN_ACADEMY_RELEASE_TOKEN` takes a grant, deployment or learner token instead
`--version <x.y.z>`	install this exact version instead of the channel's newest; a yanked version is still served when pinned this way
`--channel stable\|preview`	catalogue channel (default the one this build pins)
`--from <archive-or-binary>`	install from a file instead of the Academy Server: the pinned release archive for this platform, or an agent binary
`--force`	reinstall even when this release is already installed

$ opschain academy install --grant-file ~/opschain.grant
resolved academy-opschain-agent 0.2.0 (stable channel, sdk 0.4.0) through https://academy.limepoint.com — catalogue signed by key 472ef203071f6fe7; downloading academy-opschain-agent_0.2.0_darwin_arm64.tar.gz with the grant-file credential
installed academy-opschain-agent v0.2.0 (sha256 2cb7…) at /Users/me/.opschain/academy/bin/academy-opschain-agent
Next: opschain academy serve …  (or `opschain docs cli/academy-serve`)

$ opschain academy install
Error: academy install downloads the agent from the Academy Server with your Academy credential — pass --grant-file <file> (the registration grant LimePoint issued your organisation; ACADEMY_AGENT_GRANT_FILE), or set OPSCHAIN_ACADEMY_RELEASE_TOKEN to a registration grant, a deployment token or a learner token; an air-gapped machine installs from a file with --from instead

$ opschain academy install --from ~/Downloads/academy-opschain-agent_0.1.0_darwin_arm64.tar.gz
installed academy-opschain-agent v0.1.0 (sha256 c173…) at /Users/me/.opschain/academy/bin/academy-opschain-agent

Refusals, each by name: the organisation is not entitled to the agent; the version was yanked (and not pinned by --version); the channel has no installable version; the credential was not accepted; the catalogue's signature does not verify, or the server's current key is not the one this build pins; the download's digest differs from the catalogue's; the catalogue's version is below the floor this build pins; the server is unreachable — in which case the refusal points at --from.

-o json / -o yaml print the installed record and the path.

Exit codes: 0 installed (or already installed); 1 the server refused, the signature or digest did not verify, the archive held no agent, the file could not be read, or no release is pinned for a --from archive; 2 no credential was given, --from was mixed with the server lane's flags, or the channel is not stable or preview.

See also​

See also