kibana-cli

English | 中文

Kibana log query CLI for humans and AI Agents. All queries go through Kibana Console Proxy (HTTP Basic). Built for managed ELK (e.g. Kibana 7.7+).

Why kibana-cli?

Many teams only expose a Kibana URL for log access. kibana-cli wraps high-intensity search and agg with an Agent-friendly JSON-by-default contract, following jira-cli and gitlab-cli:

• Default JSON contract — every JSON response is a single envelope with ok, schema_version, data or error, and meta (all on stdout)
• field-map.yaml (optional) — logical service names across heterogeneous indices; index_rules in field-map.example.yaml
• --data-view — resolve index pattern from a Kibana data view id
• --dry-run + --confirm — preview write actions with a confirm token; search/agg dry-runs do not call Kibana (including --data-view, which uses a placeholder index in the preview)
• update — check GitHub Releases and update standalone binaries after checksum verification; package-manager installs get the correct npm / go install command
• --force — overwrite existing field-map.yaml on config init
• --insecure / --timeout
• Machine-readable error envelopes — error.code, error.message, error.details, and error.retryable
• Semantic exit codes (0-8)
• SKILL.md — npx skills add fatecannotbealtered/kibana-cli

Install

Quick start

Copy the block below to your agent (or run it yourself):

# Please install kibana-cli and use it for all Kibana log search/aggregation going forward. Output defaults to JSON.
# Install CLI
npm install -g @fatecannotbealtered-/kibana-cli

# Install CLI Skill (required) — copies into your agent-supported skills directory
npx skills add fatecannotbealtered/kibana-cli -y -g

# Configure (env vars for CI/agents; or use auth login with dry-run/confirm)
export KIBANA_CLI_HOST=https://kibana.example.com
export KIBANA_CLI_USER=dev_ro
export KIBANA_CLI_PASSWORD='...'

# Verify
kibana-cli context

# Windows PowerShell
$env:KIBANA_CLI_HOST = "https://kibana.example.com"
$env:KIBANA_CLI_USER = "dev_ro"
$env:KIBANA_CLI_PASSWORD = "..."

kibana-cli context

The CLI package provides the kibana-cli binary; the Skill package teaches compatible AI coding assistants how to use it safely.

Prefer saved login? Credentials are stored in the OS credential store by default. Writes are non-interactive and require dry-run confirmation:

kibana-cli auth login --host https://kibana.example.com --user dev_ro --password '...' --dry-run
kibana-cli auth login --host https://kibana.example.com --user dev_ro --password '...' --confirm <confirm_token>
kibana-cli context

Alternative: Go install

go install github.com/fatecannotbealtered/kibana-cli/cmd/[email protected]

Alternative: Download binary

Download from GitHub Releases and add to your PATH.

Update

kibana-cli update --check
kibana-cli update --dry-run
kibana-cli update --confirm <confirm_token>

update checks GitHub Releases. Standalone Unix binaries are replaced in place only after checksums.txt SHA256 verification and --confirm. If the CLI is managed by npm or Go, it does not mutate those managed files and returns the exact command to run, for example npm install -g @fatecannotbealtered-/[email protected] or go install github.com/fatecannotbealtered/kibana-cli/cmd/[email protected].

Authentication

HTTP Basic only (Kibana username/password). Prefer env vars in CI/agents — avoid --password on argv.

kibana-cli auth login --host https://kibana.example.com --user dev_ro --password '...' --dry-run
kibana-cli auth login --host https://kibana.example.com --user dev_ro --password '...' --confirm <confirm_token>
kibana-cli context
kibana-cli auth status

Secrets default to the OS credential store; config.json has no plaintext password.

| Variable | Description | |----------|-------------| | KIBANA_CLI_HOST | Kibana base URL | | KIBANA_CLI_USER / KIBANA_CLI_PASSWORD | HTTP Basic | | KIBANA_CLI_KIBANA_VERSION | Optional; skip auto-detect | | KIBANA_CLI_INSECURE | 1 or true — skip TLS verification | | KIBANA_CLI_TIMEOUT | HTTP timeout seconds (default 60) | | KIBANA_CLI_ALLOWED_INDEX_PREFIXES | Optional comma-separated prefixes; index pattern must start with one of them |

Exit codes

| Code | Meaning | |------|---------| | 0 | OK | | 1 | General error | | 2 | Bad args / usage error | | 3 | Resource not found | | 4 | Auth / permission failure | | 5 | Confirmation required | | 6 | Precondition conflict | | 7 | Retryable transient error (network / rate limit / server) | | 8 | Timeout |

Commands

Run kibana-cli reference --format text for the full human-readable command tree.

kibana-cli auth login|logout|status
kibana-cli context
kibana-cli doctor
kibana-cli config init|show
kibana-cli patterns list|fields
kibana-cli search --index 'app-test-log-*' --level ERROR
kibana-cli search --data-view <uuid> --query 'timeout'
kibana-cli agg --index 'app-test-log-*' --terms level --from now-1h
kibana-cli update --check

search defaults to --from now-15m (omit --from to use that window).

Optional ~/.kibana-cli/field-map.yaml (kibana-cli config init). Profiles and index_rules (glob overrides per index) are documented in field-map.example.yaml.

Output flags: --format json|text|raw (default json), --compact (JSON only), --quiet (suppresses auxiliary text output only), and --json as a compatibility alias for --format json. --fields only affects JSON output, and unsupported formats return an explicit parameter error.

Other global flags: --dry-run, --confirm, --force (overwrite field-map.yaml on config init), --timeout, --insecure (or KIBANA_CLI_INSECURE=1 / true).

Agent workflow

kibana-cli context              # auth + log search reachability (read top-level ok first)
kibana-cli patterns fields      # discover fields on an index pattern
kibana-cli search ...           # primary: query logs
kibana-cli agg ...              # count by level / service

For JSON output, read top-level ok first. Success data is under data; failure details are under error.details.

License

MIT