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).

Your opschain login session plays no part in the install: it is the Academy credential above that identifies the download. The login matters when the agent runs — academy serve and academy register prove the stored session (renewing a stale access token), refuse an expired login by name, and mint the agent a scoped API token (academy-agent <label>, 30 days, revoked when the agent exits) rather than handing it the session itself; OPSCHAIN_ACADEMY_TOKEN set by you overrides that. The rule is spelled out under "The credential" in opschain docs cli/academy-serve.

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

• opschain docs cli/academy-show — what is pinned and installed, and which server and channel the build follows.
• opschain docs packs-academy — how the agent is published to and served by the Academy Server.