Monoscope full color logo
Sign Up
Home Getting Started SDK Guides AI Dashboard API Reference
CLI & Agents
MCP Server

On this page

Open in ChatGPT Open in Claude Open in Perplexity

Install & Authenticate

A single static binary on Linux and macOS, x86_64 and arm64. No runtime, no Docker, no package-manager dance — curl | sh and you’re done.

Install

Specific version

curl https://monoscope.tech/install.sh | sh -s v1.2.3

Custom install location

MONOSCOPE_INSTALL_DIR=/usr/local/bin curl https://monoscope.tech/install.sh | sh

Upgrading

Re-running the install script upgrades to the latest release. If the binary is already current the script exits with already up to date. To force-reinstall the same version, pass --force:

curl https://monoscope.tech/install.sh | sh -s -- --force

Verify

monoscope --version
monoscope --help

Authenticate

Browser-based login (interactive)

monoscope auth login

Opens your browser, prompts you to approve a device code, then writes a session token to ~/.config/monoscope/tokens.json (mode 0600).

Token-based login (CI / non-interactive)

For CI pipelines and any environment where opening a browser is impractical, use a long-lived API key instead. Generate one in the dashboard (Settings → API Keys) or via the CLI itself once you’ve logged in:

monoscope api-keys create "ci-pipeline" -o json | jq -r .key

Then:

monoscope auth login --token <api-key>

Or skip the file altogether and pass it through environment:

export MONOSCOPE_API_KEY=<api-key>
monoscope auth status

Status & logout

monoscope auth status     # human-readable
monoscope --json auth status   # {authenticated, method, api_url, project}
monoscope auth logout     # remove ~/.config/monoscope/tokens.json

Non-interactive mode is auto-detected. Whenever stdout isn't a TTY — or when CI=1 / CLAUDE_CODE=1 is set, or you pass --json / --yaml — auth login without --token exits non-zero rather than launching a 5-minute device-code poll. Always pass a token when running unattended.

Configure

Configuration is resolved in this order (later wins):

  1. ~/.config/monoscope/config.yaml — global config
  2. .monoscope.yaml — project-local config (searched up from cwd)
  3. Environment variables

Interactive setup

monoscope config init

Manual

monoscope config set project <project-uuid>
monoscope config set api_url https://your-self-hosted-instance.example.com
monoscope config get             # show all
monoscope config get project     # show one value
monoscope --json config get      # JSON output, suitable for piping

Valid keys: api_url, project, api_key.

Environment variables

Variable Description
MONOSCOPE_API_KEY API key — takes precedence over stored token.
MONOSCOPE_PROJECT Default project UUID — overridable per-invocation with --project/-p.
MONOSCOPE_API_URL API base URL (default: https://api.monoscope.tech). Point at http://localhost:8080 to drive a self-hosted dev server.
MONOSCOPE_FORCE_COLOR Set to 1 to keep colored table output when stdout is piped (otherwise the pipe auto-detect switches to JSON).
MONOSCOPE_DEBUG Set to 1 (or pass --debug) to print every outgoing request URL and params to stderr. With --debug, the server also includes raw SQL / Hasql exception text under error.details.

Non-interactive prompts are auto-disabled whenever stdout isn’t a TTY, or when CI=1 / CLAUDE_CODE=1 is set, or you pass any of --json / --yaml / --table (precedence: --json > --yaml > --table).

Shell completions

monoscope completion bash >> ~/.bashrc
monoscope completion zsh  >> ~/.zshrc
monoscope completion fish >> ~/.config/fish/completions/monoscope.fish

Unknown shells exit non-zero with a clear error rather than silently emitting a bash script.

See also