Skip to content

install-cli.md

Latest commit

 

History

History
236 lines (167 loc) · 6.99 KB

install-cli.md

File metadata and controls

236 lines (167 loc) · 6.99 KB

Installing the insight CLI

The insight CLI is a small GraalVM native binary that talks to the ebean-insight-server /v1 API — list apps and environments, browse captured DB query plans, and request fresh plan captures.

For day-to-day usage (commands, flags, daemon mode, config persistence, authentication, JSON output) see cli/README.md.

Automating this for an AI agent? See the non-interactive, idempotent install/upgrade recipe in install-cli-agents.md.

Where to get a binary

Per-OS native binaries are published as GitHub Release assets when a v* tag is pushed (recommended), and as workflow artifacts for every run of the CLI native binaries workflow (useful for unreleased commits).

Asset name (in Release zip) OS / arch Binary inside the zip
insight-linux-x64-v<version>.zip Linux x86_64 insight
insight-macos-arm64-v<version>.zip macOS Apple Silicon insight
insight-windows-x64-v<version>.zip Windows x86_64 insight.exe

Not in the matrix today: macOS Intel (x86_64), Linux arm64. Use build from source for those targets.

Download from the latest GitHub Release (recommended)

# macOS (Apple Silicon)
curl -L -o insight.zip \
  https://github.com/ebean-orm/ebean-insight-server/releases/latest/download/insight-macos-arm64-<version>.zip

# Linux (x86_64)
curl -L -o insight.zip \
  https://github.com/ebean-orm/ebean-insight-server/releases/latest/download/insight-linux-x64-<version>.zip

# Windows (PowerShell)
Invoke-WebRequest -OutFile insight.zip `
  https://github.com/ebean-orm/ebean-insight-server/releases/latest/download/insight-windows-x64-<version>.zip

Replace <version> with the tag (e.g. v2.0). You can browse all releases at Releases.

Verify checksums (recommended)

Each Release ships a SHA256SUMS file covering every CLI archive:

curl -LO https://github.com/ebean-orm/ebean-insight-server/releases/latest/download/SHA256SUMS
shasum -a 256 -c SHA256SUMS --ignore-missing

Download via gh CLI

# Latest release zip for your platform
gh release download -R ebean-orm/ebean-insight-server \
  --pattern 'insight-macos-arm64-*.zip'

Workflow artifacts (unreleased commits)

For an unreleased commit, the workflow runs produce zipped artifacts named after each platform. Download via the GitHub UI Artifacts section, or:

RUN_ID=$(gh run list -R ebean-orm/ebean-insight-server \
  -w cli-native.yml -s success --limit 1 --json databaseId -q '.[0].databaseId')

gh run download "$RUN_ID" -R ebean-orm/ebean-insight-server -n insight-macos-arm64

macOS (Apple Silicon)

# 1. Download (see above) and unzip
unzip insight-macos-arm64.zip          # produces ./insight

# 2. Mark executable and remove the Gatekeeper quarantine flag
chmod +x insight
xattr -d com.apple.quarantine insight 2>/dev/null || true

# 3. Move onto your PATH
sudo mv insight /usr/local/bin/
# (no-sudo alternative: mv insight ~/.local/bin/ — ensure ~/.local/bin is on your PATH)

# 4. Verify
insight --version

Expected:

ebean-insight-cli <version>
commit: <git-sha>
built: <build-time>

macOS Intel (x86_64): not in the current build matrix. Build from source (below) on an Intel Mac. Apple-Silicon binaries will not run under Rosetta (native-image targets the host arch).

Linux (x86_64)

unzip insight-linux-x64.zip
chmod +x insight
sudo mv insight /usr/local/bin/
insight --version

No-sudo alternative: mv insight ~/.local/bin/. If ~/.local/bin isn't on your PATH (common if the directory didn't already exist — check with which insight), add it to your shell profile and reload:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
exec $SHELL -l

Or install system-wide with sudo mv insight /usr/local/bin/ instead.

Linux arm64: not in the current build matrix; build from source.

Windows (x86_64)

# 1. Download insight-windows-x64.zip from the workflow run, unzip to get insight.exe.

# 2. Move it to a directory on your PATH, e.g. %USERPROFILE%\bin
mkdir $env:USERPROFILE\bin -Force | Out-Null
Move-Item insight.exe $env:USERPROFILE\bin\

# 3. Add it to PATH for the current user (one-time)
$current = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$current;$env:USERPROFILE\bin", "User")

# 4. Open a new terminal and verify
insight --version

WSL2 users can also use the Linux x86_64 binary.

Build from source

For unsupported OS/arch combinations or local development. Requires a GraalVM JDK on JAVA_HOME.

sdk install java 24-graal      # if using SDKMAN
sdk use java 24-graal

git clone https://github.com/ebean-orm/ebean-insight-server.git
cd ebean-insight-server
mvn -pl cli -am -Pnative -DskipTests package
./cli/target/insight --version

See cli/README.md for the JVM-mode runner that skips the native build during development.

First-run setup

Once insight --version works, point the CLI at your server. Two ways:

Via Kubernetes port-forward (default, recommended)

Persist your cluster target once so every command picks it up automatically:

insight config set namespace ebean-insight
insight config set service ebean-insight
insight config set context my-cluster      # optional
insight envs                                # smoke test

This requires the RBAC verbs documented in install-server.md (pods/portforward in the target namespace).

Via a static URL (Ingress, port-forward you manage yourself)

insight envs --url https://insight.example.com

If the server has JWT auth enabled (insight.auth.enabled=true), authenticate first with insight login (OAuth2 / Cognito) — the CLI then sends Authorization: Bearer <token> on every request. See the Authentication section of the CLI README.

For both modes, see cli/README.md for the full command reference, daemon mode (insight forward), JSON output, and config precedence rules.

Upgrading

Download the new Release zip (or workflow artifact for unreleased commits) and overwrite the binary on your PATH. insight --version shows the installed version and git commit so you can confirm the upgrade.

Uninstall

# macOS / Linux
sudo rm /usr/local/bin/insight   # or, if installed there: rm ~/.local/bin/insight
rm -rf ~/.insight                # removes persisted config + daemon advert

# Windows
Remove-Item $env:USERPROFILE\bin\insight.exe
Remove-Item -Recurse -Force $env:USERPROFILE\.insight