Skip to content

cli.mdx

Latest commit

 

History

History
259 lines (180 loc) · 6.28 KB

cli.mdx

File metadata and controls

259 lines (180 loc) · 6.28 KB
Raw
title CLI reference
description The instalog CLI for indexing, config validation, and ops.

The instalog CLI runs locally against your repository and against the Instalog API. It indexes code for the embedding store, validates configs, and surfaces dashboard data without leaving the terminal.

Install

macOS / Linux

curl -fsSL https://install.instalog.dev | bash

Homebrew

brew install instalog-dev/tap/instalog

From source

git clone https://github.com/instalog-dev/cli
cd cli
cargo build --release
# binary at ./target/release/instalog

Authentication

Get an API key from Dashboard → Settings → API Keys, then:

instalog auth login
# or set the env var
export INSTALOG_API_KEY="ilg_..."

instalog auth login stores the key in ~/.config/instalog/credentials (mode 0600). For CI, prefer the env var.

For self hosted, point at your endpoint:

export CODE_REVIEW_API_URL="https://instalog.example.com"

Commands

instalog index

Index a Git repository tree into the embedding store. The reviewer reads this index for cross file context.

instalog index [OPTIONS] [REPO]

Arguments:

  • REPO — path to the Git repo. Defaults to ..

Options:

  • --rev <REV> — revision to index (SHA, ref, revspec). Default HEAD.
  • --extensions-url <URL> — override the file type catalog URL. Env: INSTALOG_EXTENSIONS_URL.
  • --extensions-file <FILE> — local file type catalog. Skips the network. Env: INSTALOG_EXTENSIONS_FILE.
  • --ttl-days <DAYS> — cache TTL for the fetched extensions. Default 30. Env: INSTALOG_EXTENSIONS_TTL_DAYS.
  • --max-size-mb <MB> — skip files larger than this. Default 5.
  • --format <FORMAT> — text or json (NDJSON). Default text.
  • --hash — include the blob OID in output.
  • --deny-dirs <DIR> — exclude a directory. Repeatable.
  • --api-url <URL> — override API URL. Env: CODE_REVIEW_API_URL.
  • --api-key <KEY> — API key. Env: INSTALOG_API_KEY.
  • --submit-to-api / --no-submit-to-api — submit symbols after indexing. Default on.

Examples:

# Index HEAD of the current repo
instalog index

# Index a specific commit
instalog index /path/to/repo --rev abc123

# JSON output with content hashes
instalog index --format json --hash

# Exclude build artifacts
instalog index --deny-dirs node_modules --deny-dirs target

# Dry run (don't submit)
instalog index --no-submit-to-api

The index reads Git objects directly. No working copy scan, so an index on a clean ref is reproducible.

instalog repo-index

Manage repository indexes server side.

instalog repo-index list

instalog repo-index list [--api-url <URL>] [--api-key <KEY>]

Returns the list of repos with an index, last indexed SHA, and embedding count.

instalog repo-index get <REPO_ID>

instalog repo-index get owner/repo

Returns detail on one repo: index version, embedding count, last reviewed PR, drop rate.

instalog repo-index delete <REPO_ID>

instalog repo-index delete owner/repo --yes

Drops the embedding index. The next PR rebuilds it on demand. Useful when the schema changes or when an index is corrupt.

instalog config

Validate instalog-ai.yaml without pushing it.

instalog config validate ./instalog-ai.yaml
instalog config schema > schema.json     # dump the JSON schema
instalog config defaults                 # print the effective defaults

validate exits non zero on any error and prints actionable messages. Wire it into CI to catch broken configs before merge.

instalog reviews

Inspect review history.

# Recent reviews for a repo
instalog reviews list --repo owner/repo --since 7d

# Detail on one review
instalog reviews get --repo owner/repo --pr 482

# Skipped reviews and why
instalog reviews skipped --repo owner/repo --since 7d

# Findings dropped, by reason
instalog reviews dropped --repo owner/repo --since 30d

--format json returns NDJSON for piping into jq.

instalog rules

Inspect rule performance.

# Top firing rules in the last 30 days
instalog rules hits --repo owner/repo --since 30d

# Acceptance rate per rule
instalog rules acceptance --repo owner/repo --since 30d

# Diff your custom rules against base
instalog rules diff

instalog mcp

Run the MCP server. Used by Claude Desktop and other MCP clients.

instalog mcp serve --port 4242

See MCP for client setup.

instalog preflight

Pre flight checks for upgrades and ops.

# Check upgrade compatibility for self hosted
instalog preflight upgrade --target 2.5.0

# Validate cluster health
instalog preflight cluster

instalog auth

instalog auth login           # interactive
instalog auth logout
instalog auth whoami          # print current org and user

Env vars

Var Purpose
INSTALOG_API_KEY API key for all commands.
CODE_REVIEW_API_URL API base URL. Default https://api.instalog.dev.
INSTALOG_EXTENSIONS_URL Override the file type catalog URL.
INSTALOG_EXTENSIONS_FILE Local catalog file.
INSTALOG_EXTENSIONS_TTL_DAYS Catalog cache TTL.
INSTALOG_PROFILE Named profile from ~/.config/instalog/config.toml.
NO_COLOR Disable ANSI color in output.
INSTALOG_LOG Log level: error, warn, info, debug, trace.

Profiles

For multiple environments (prod, staging, self hosted), put profiles in ~/.config/instalog/config.toml:

[profiles.prod]
api_url = "https://api.instalog.dev"

[profiles.staging]
api_url = "https://staging.instalog.dev"

[profiles.internal]
api_url = "https://instalog.example.internal"

Then:

instalog --profile internal reviews list --repo my-org/api
# or
INSTALOG_PROFILE=internal instalog reviews list ...

Shell completion

# bash
instalog completion bash > /etc/bash_completion.d/instalog
# zsh
instalog completion zsh > "${fpath[1]}/_instalog"
# fish
instalog completion fish > ~/.config/fish/completions/instalog.fish

Exit codes

Code Meaning
0 Success.
1 Generic error.
2 Argument or config error.
3 API error (4xx/5xx).
4 Auth error (401/403).
5 Rate limit (429). Retry after the delay in the response.