Skip to content

install.md

Latest commit

 

History

History
353 lines (245 loc) · 17.8 KB

install.md

File metadata and controls

353 lines (245 loc) · 17.8 KB
title Install Agora CLI

Install Agora CLI

This page lists the supported installation paths for Agora CLI and the direct installers for macOS, Linux, and Windows.

Direct Installers

macOS, Linux, and Windows POSIX shells

Install the latest release:

curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh
agora --help

Shell setup is auto-on. The default install adds the install directory to your shell rc when agora isn't already on PATH, and writes a tab-completion script for the detected shell (bash, zsh, fish). Pass --no-path, --no-completion, or the umbrella --skip-shell to opt out granularly.

Install a pinned version:

curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh -s -- --version 0.2.0
agora --help

Install to a user-writable directory:

curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh \
  | INSTALL_DIR="$HOME/.local/bin" sh
agora --help

Install only the binary (no shell modifications):

curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh -s -- --skip-shell

Run a dry run before installing:

curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh -s -- --dry-run

The shell installer supports macOS, Linux, and Windows POSIX shells such as Git Bash, MSYS2, and Cygwin. On macOS and Linux, the default install directory is /usr/local/bin; when that directory requires elevation and sudo is unavailable in the current shell, the installer falls back to a user-writable directory such as $HOME/.local/bin. On Windows POSIX shells, the default install directory is $HOME/bin and the installed binary is agora.exe.

The shell installer is idempotent. Re-running with the same --version will detect the existing install at the target install directory and exit successfully without re-downloading. Pass --force to reinstall.

Windows (PowerShell)

Install the latest release:

irm https://raw.githubusercontent.com/AgoraIO/cli/main/install.ps1 | iex
agora --help

The PowerShell installer wires the install directory onto your user PATH and writes a completion loader into your $PROFILE automatically. Pass -NoPath, -NoCompletion, or the umbrella -SkipShell to opt out granularly.

Install a pinned version:

$env:VERSION = "0.2.0"
irm https://raw.githubusercontent.com/AgoraIO/cli/main/install.ps1 | iex
agora --help

Install only the binary (no shell modifications):

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/AgoraIO/cli/main/install.ps1))) -SkipShell

The Windows installer installs agora.exe into %LOCALAPPDATA%\Programs\Agora\bin by default.

If your PowerShell execution policy blocks inline scripts, download install.ps1 first and run it with powershell -ExecutionPolicy Bypass -File .\install.ps1.

Unix Installer Flags

--version VERSION       Install a specific version (with or without leading 'v').
--dir INSTALL_DIR       Install directory (default: /usr/local/bin on macOS/Linux,
                        $HOME/bin on Windows POSIX shells).
--prerelease            Resolve latest including GitHub prereleases.
--list-versions         Print recent published versions and exit.
--force                 Reinstall even if the requested version is present, or
                        proceed past an existing managed install warning.

# Shell integration (auto-on; pass an opt-out flag to disable)
--no-path               Don't append the install directory to your shell rc file.
--no-completion         Don't install shell completion.
--skip-shell            Umbrella for --no-path --no-completion.

--dry-run               Show what would happen without writing any files.
--uninstall             Remove the installer-managed binary and receipt.
--no-color              Disable colored output.
-q, --quiet             Suppress non-error output.
-v, --verbose           Verbose debug output (installer-internal; unrelated to
                        the agora CLI's --debug flag).
--installer-version     Print this installer's revision and exit.
-h, --help              Show full help.

PowerShell Installer Parameters

-Version <string>       Install a specific version.
-InstallDir <string>    Install directory (default: %LOCALAPPDATA%\Programs\Agora\bin).
-GitHubRepo <string>    Install from a fork or alternate repository.
-Force                  Reinstall even if the requested version is present.
-NoColor                Disable colored output.
-Uninstall              Remove the installer-managed binary and receipt.

# Shell integration (auto-on; pass an opt-out switch to disable)
-NoPath                 Don't add the install directory to your user PATH.
-NoCompletion           Don't wire completion into your PowerShell $PROFILE.
-SkipShell              Umbrella for -NoPath -NoCompletion.

If another managed agora install is detected, the installer refuses by default to avoid creating two installs that shadow each other on PATH. Pass --force to install alongside it.

Uninstall

Direct installer installs can be removed with:

curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh -s -- --uninstall

On Windows PowerShell:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/AgoraIO/cli/main/install.ps1))) -Uninstall

Uninstall removes the binary and agora.install.json receipt from the install directory. It preserves config, session, context, and logs.

Supported Environment Variables

Both direct installers support these core overrides:

  • GITHUB_REPO: install from a fork or alternate repository.
  • VERSION: install a specific version. Both 0.2.0 and v0.2.0 are accepted.
  • INSTALL_DIR: install to a custom directory.
  • GITHUB_TOKEN or GH_TOKEN: optional GitHub token to avoid API rate limits when resolving the latest release.

Shell installer only:

  • NO_COLOR: any non-empty value disables colored output.
  • SUDO: command for privileged installs (default sudo; set to doas, sudo -n, or empty to disable elevation).
  • DOCS_URL: alternate docs URL printed in the next-steps footer.
  • ISSUES_URL: alternate issues URL printed in error messages.

Advanced or test overrides supported by both direct installers:

  • GITHUB_API_URL: alternate API base URL.
  • RELEASES_DOWNLOAD_BASE_URL: alternate release download base URL.
  • RELEASES_PAGE_URL: alternate releases page URL used in error messages.

Exit Codes

Both install.sh and install.ps1 use the same stable exit-code contract for scripted callers:

Code Meaning
0 success (or already at target version on idempotent re-run)
1 generic / unknown error
2 invalid arguments
3 missing prerequisite (curl/wget, tar/unzip, sha256sum, ... — Unix only)
4 unsupported platform / architecture
5 network or download failure
6 checksum verification failed
7 install or permission failure (non-writable dir, sudo, or refused to overwrite a managed install without --force / -Force)
8 post-install verification failed

Idempotent re-runs

Both installers short-circuit with exit 0 when the target install path already contains the target version. Pass --force (Unix) or -Force (PowerShell) to reinstall anyway.

Managed-install detection

Both installers refuse to overwrite an agora binary that came from a package manager and exit 7 with a recommended upgrade command. Override with --force / -Force.

Manager Detected by Recommended upgrade
Homebrew (Unix) binary path under brew --prefix brew upgrade agora
npm (Unix and Windows) binary path under npm prefix -g npm update -g agoraio-cli
Scoop (Windows) $env:SCOOP or path contains \scoop\shims\ scoop update agora
Chocolatey (Windows) $env:ChocolateyInstall or path contains \chocolatey\bin\ choco upgrade agora
winget (Windows) path contains \WinGet\Packages\ winget upgrade Agora.Cli

Install receipt and upgrades

Direct installer runs (install.sh and install.ps1) write agora.install.json next to the installed binary after the binary has been downloaded, checksum-verified, installed, and smoke-tested. Direct self-updates refresh the same receipt after replacing the binary. The receipt records the install method, install path, version, timestamp, and installer source so agora upgrade can choose the right update path without relying on shell environment variables.

agora upgrade uses this order:

  1. Read and validate the adjacent agora.install.json receipt.
  2. Fall back to the resolved binary path for package-manager installs (node_modules, Homebrew Cellar, Scoop, Chocolatey, or winget paths).
  3. Fall back to the direct installer path when the binary is named agora / agora.exe and no package-manager path is detected.
  4. Report unknown for development/test binaries where the install method cannot be verified.

Direct-installer installs self-update in place. Package-manager installs print the package-manager command and exit successfully so the package manager remains the owner of the installed files.

Build From Source

Requirements:

  • Go toolchain from go.mod
  • git
go build -o agora .
./agora --help

Package Channels

Channel Status Command
Shell installer Available curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh
Windows PowerShell Available irm https://raw.githubusercontent.com/AgoraIO/cli/main/install.ps1 | iex
Linux .deb / .rpm / .apk artifacts Available on GitHub releases Download the package for your distro from the release page.
apt repository Available when apt-repo.yml publishes the release Use the signed repository documented by the release.
Docker / GHCR Available when release images publish docker run --rm ghcr.io/agoraio/agora-cli:latest --help
npm wrapper Available npm install -g agoraio-cli
Homebrew / Scoop Coming soon Use the direct installer until package-manager taps are published.

npm wrapper

The agoraio-cli npm package is a thin Node.js shim that resolves the right native binary for your platform via optionalDependencies. The platform binary itself is the same artifact published to GitHub Releases. Each release is published with npm provenance so consumers can verify the package was built from this repository's release workflow.

# Install globally
npm install -g agoraio-cli
agora --help

# Or run without a global install
npx agoraio-cli --help

# Pin a specific version
npm install -g agoraio-cli@0.2.0

# Update to the latest published version
npm update -g agoraio-cli

Supported platforms: darwin-arm64, darwin-x64, linux-arm64, linux-x64, win32-x64, win32-arm64. Node 18 or newer is required. If you see "platform package not installed," run npm install -g agoraio-cli again.

Shell Completion

Generate completion scripts with Cobra's built-in command:

agora completion bash
agora completion zsh
agora completion fish
agora completion powershell

For one-off shell sessions, source the generated script according to your shell's completion setup.

Troubleshooting

GitHub API rate limits

If latest-version resolution fails, retry with a pinned version or provide GITHUB_TOKEN / GH_TOKEN:

GITHUB_TOKEN=your-token-here VERSION=0.2.0 sh install.sh
$env:GITHUB_TOKEN = "your-token-here"
$env:VERSION = "0.2.0"
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/AgoraIO/cli/main/install.ps1)))

Permission errors

  • On macOS and Linux, prefer INSTALL_DIR="$HOME/.local/bin" if you do not want sudo. The installer refuses to prompt for sudo when stdin is not a TTY (the typical curl | sh case) and falls back to a user-writable default when possible.
  • On Windows, choose a writable -InstallDir or run PowerShell elevated if you are installing into a system directory.

"Detected managed install"

The shell installer refuses to install over an existing managed agora to avoid creating two installs that shadow each other on PATH. Either:

  • Keep using the existing install, or
  • Re-run the installer with --force to install alongside it.

PATH issues

If agora installs successfully but is not found, you most likely ran the installer with --no-path / --skip-shell (or -NoPath / -SkipShell on Windows). The default install wires PATH automatically.

  • macOS, Linux, and Windows POSIX shells: re-run the installer without the --no-path / --skip-shell flag, or add INSTALL_DIR to your shell profile manually, for example export PATH="$HOME/.local/bin:$PATH".
  • Windows: re-run install.ps1 without -NoPath / -SkipShell, or add %LOCALAPPDATA%\Programs\Agora\bin to your user PATH manually, then open a new terminal.

Checksum failures

The installers verify release artifacts against the published checksums.txt. If checksum verification fails, the installer prints the expected and actual SHA256 and exits with code 6. Do not continue with the install. Retry the download, confirm the requested version exists on the GitHub release, and check whether a proxy or cache is rewriting downloads.

Proxies and restricted networks

The installers rely on your platform's normal HTTP proxy settings. If downloads fail behind a corporate proxy, retry with the appropriate proxy environment configured and prefer a pinned VERSION. The Unix installer enables curl --retry 3 --retry-connrefused with sane connect and total timeouts by default.

Security

The shell installer:

  • Restricts curl to --proto =https --tlsv1.2, refusing plain HTTP and legacy TLS when curl is used.
  • Verifies every artifact against the published checksums.txt before installing.
  • Installs atomically: the binary is written to a temp path inside INSTALL_DIR and renamed only after extraction and checksum verification succeed. Interrupted runs leave no partial binary behind.

For CI, automation, and reproducible environments, pin VERSION explicitly instead of relying on the latest release lookup.

Verify release artifacts (Cosign + SBOM)

Every release is signed with Cosign using GitHub Actions OIDC (keyless mode) and ships an SPDX 2.3 SBOM per archive and per Linux package. To verify the checksums.txt file before trusting any artifact:

TAG=v0.2.0
ASSET_BASE="https://github.com/AgoraIO/cli/releases/download/${TAG}"
curl -fsSLO "${ASSET_BASE}/checksums.txt"
curl -fsSLO "${ASSET_BASE}/checksums.txt.sig"
curl -fsSLO "${ASSET_BASE}/checksums.txt.pem"

cosign verify-blob \
  --certificate-identity-regexp '^https://github.com/AgoraIO/cli/' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  --certificate checksums.txt.pem \
  --signature checksums.txt.sig \
  checksums.txt

Once checksums.txt is verified, the existing SHA-256 entries inside it transitively cover every release archive.

The published Docker images are also signed:

cosign verify "ghcr.io/agoraio/agora-cli:${TAG#v}" \
  --certificate-identity-regexp '^https://github.com/AgoraIO/cli/' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com'

To audit dependencies, download the *.spdx.json SBOM that ships next to each archive (e.g. agora-cli-go_v0.2.0_linux_amd64.tar.gz.spdx.json) and feed it to a scanner such as Grype:

grype sbom:agora-cli-go_v0.2.0_linux_amd64.tar.gz.spdx.json