# kitproj/splunk-cli architecture

> Architecture diagram of the GitHub repository kitproj/splunk-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kitproj/splunk-cli
- Repository: https://github.com/kitproj/splunk-cli

## Overview

Splunk CLI & MCP Server provides two user-facing entry points for searching Splunk: a command-line command and an MCP tool over stdio. Both create a search job, poll its status, retrieve results, and format them for the caller. CLI configuration stores the host in a config file and the token in the system keyring; the README also documents environment-variable fallback for CLI use. The client implements additional saved-search, alert, server-info, and event operations, but no sampled caller connects these to a user-facing route. The MCP server's sampled configuration path uses config and keyring; its documented environment fallback is not visible in that implementation.

Main entry points: [`main.go`](https://github.com/kitproj/splunk-cli/blob/main/main.go) (CLI Commands), [`mcp.go`](https://github.com/kitproj/splunk-cli/blob/main/mcp.go) (MCP Server), [`internal/splunk/client.go`](https://github.com/kitproj/splunk-cli/blob/main/internal/splunk/client.go) (Search Jobs), [`internal/config/config.go`](https://github.com/kitproj/splunk-cli/blob/main/internal/config/config.go) (Host Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Entry Points"]
  node_cli["CLI Commands<br/>[main.go]"]
  node_mcp_server["MCP Server<br/>[mcp.go]"]
  node_mcp_search["MCP Search Tool<br/>[mcp.go]"]
end

subgraph group_search["Search Execution"]
  node_cli_search["CLI Search<br/>[main.go]"]
  node_mcp_handler["MCP Search Handler<br/>[mcp.go]"]
end

subgraph group_config["Credentials and Config"]
  node_configure["Configure Credentials<br/>[main.go]"]
  node_config_store[("Host Config<br/>[config.go]")]
  node_keyring[("Token Keyring<br/>[config.go]")]
end

subgraph group_splunk["Splunk API"]
  node_search_jobs["Search Jobs<br/>[client.go]"]
  node_search_status["Search Status<br/>[client.go]"]
  node_search_results["Search Results<br/>[client.go]"]
  node_saved_searches["Saved Searches<br/>[client.go]"]
  node_alerts["Scheduled Alerts<br/>[client.go]"]
  node_server_info["Server Info<br/>[client.go]"]
  node_event_collector["Event Collector<br/>[client.go]"]
end

node_cli_user(("CLI User"))
node_mcp_client(("MCP Client"))
node_splunk_instance["Splunk Instance"]

node_cli_user -->|"runs commands"| node_cli
node_cli -->|"dispatches configure"| node_configure
node_cli -->|"dispatches search"| node_cli_search
node_cli -->|"dispatches server"| node_mcp_server
node_mcp_client -->|"starts stdio"| node_mcp_server
node_mcp_server -->|"registers tool"| node_mcp_search
node_mcp_search -->|"invokes handler"| node_mcp_handler
node_configure -->|"saves host"| node_config_store
node_configure -->|"saves token"| node_keyring
node_cli -->|"loads host"| node_config_store
node_cli -->|"loads token"| node_keyring
node_mcp_server -->|"loads host"| node_config_store
node_mcp_server -->|"loads token"| node_keyring
node_cli_search -->|"creates job"| node_search_jobs
node_cli_search -->|"polls status"| node_search_status
node_cli_search -->|"fetches results"| node_search_results
node_mcp_handler -->|"creates job"| node_search_jobs
node_mcp_handler -->|"polls status"| node_search_status
node_mcp_handler -->|"fetches results"| node_search_results
node_search_jobs -->|"submits search"| node_splunk_instance
node_search_status -->|"queries status"| node_splunk_instance
node_search_results -->|"fetches results"| node_splunk_instance
node_saved_searches -->|"manages searches"| node_splunk_instance
node_alerts -->|"lists alerts"| node_splunk_instance
node_server_info -->|"queries info"| node_splunk_instance
node_event_collector -->|"sends events"| node_splunk_instance

click node_cli "https://github.com/kitproj/splunk-cli/blob/main/main.go"
click node_mcp_server "https://github.com/kitproj/splunk-cli/blob/main/mcp.go"
click node_mcp_search "https://github.com/kitproj/splunk-cli/blob/main/mcp.go"
click node_configure "https://github.com/kitproj/splunk-cli/blob/main/main.go"
click node_config_store "https://github.com/kitproj/splunk-cli/blob/main/internal/config/config.go"
click node_keyring "https://github.com/kitproj/splunk-cli/blob/main/internal/config/config.go"
click node_cli_search "https://github.com/kitproj/splunk-cli/blob/main/main.go"
click node_mcp_handler "https://github.com/kitproj/splunk-cli/blob/main/mcp.go"
click node_search_jobs "https://github.com/kitproj/splunk-cli/blob/main/internal/splunk/client.go"
click node_search_status "https://github.com/kitproj/splunk-cli/blob/main/internal/splunk/client.go"
click node_search_results "https://github.com/kitproj/splunk-cli/blob/main/internal/splunk/client.go"
click node_saved_searches "https://github.com/kitproj/splunk-cli/blob/main/internal/splunk/client.go"
click node_alerts "https://github.com/kitproj/splunk-cli/blob/main/internal/splunk/client.go"
click node_server_info "https://github.com/kitproj/splunk-cli/blob/main/internal/splunk/client.go"
click node_event_collector "https://github.com/kitproj/splunk-cli/blob/main/internal/splunk/client.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_mcp_server,node_mcp_search,node_cli_user,node_mcp_client toneBlue
class node_cli_search,node_mcp_handler toneAmber
class node_configure,node_config_store,node_keyring toneMint
class node_search_jobs,node_search_status,node_search_results,node_saved_searches,node_alerts,node_server_info,node_event_collector toneRose
class node_splunk_instance toneIndigo
```

## Components

### User Entry Points

- [CLI Commands](https://github.com/kitproj/splunk-cli/blob/main/main.go): `main.go`
- [MCP Server](https://github.com/kitproj/splunk-cli/blob/main/mcp.go): `mcp.go`
- [MCP Search Tool](https://github.com/kitproj/splunk-cli/blob/main/mcp.go): `mcp.go`

### Search Execution

- [CLI Search](https://github.com/kitproj/splunk-cli/blob/main/main.go): `main.go`
- [MCP Search Handler](https://github.com/kitproj/splunk-cli/blob/main/mcp.go): `mcp.go`

### Credentials and Config

- [Configure Credentials](https://github.com/kitproj/splunk-cli/blob/main/main.go): `main.go`
- [Host Config](https://github.com/kitproj/splunk-cli/blob/main/internal/config/config.go): `internal/config/config.go`
- [Token Keyring](https://github.com/kitproj/splunk-cli/blob/main/internal/config/config.go): `internal/config/config.go`

### Splunk API

- [Search Jobs](https://github.com/kitproj/splunk-cli/blob/main/internal/splunk/client.go): `internal/splunk/client.go`
- [Search Status](https://github.com/kitproj/splunk-cli/blob/main/internal/splunk/client.go): `internal/splunk/client.go`
- [Search Results](https://github.com/kitproj/splunk-cli/blob/main/internal/splunk/client.go): `internal/splunk/client.go`
- [Saved Searches](https://github.com/kitproj/splunk-cli/blob/main/internal/splunk/client.go): `internal/splunk/client.go`
- [Scheduled Alerts](https://github.com/kitproj/splunk-cli/blob/main/internal/splunk/client.go): `internal/splunk/client.go`
- [Server Info](https://github.com/kitproj/splunk-cli/blob/main/internal/splunk/client.go): `internal/splunk/client.go`
- [Event Collector](https://github.com/kitproj/splunk-cli/blob/main/internal/splunk/client.go): `internal/splunk/client.go`

### Other components

- **CLI User**
- **MCP Client**
- **Splunk Instance**

## Connections

- CLI User → CLI Commands: runs commands (evidence: `README.md`)
- CLI Commands → Configure Credentials: dispatches configure (evidence: `main.go`)
- CLI Commands → CLI Search: dispatches search (evidence: `main.go`)
- CLI Commands → MCP Server: dispatches server (evidence: `main.go`)
- MCP Client → MCP Server: starts stdio (evidence: `README.md`)
- MCP Server → MCP Search Tool: registers tool (evidence: `mcp.go`)
- MCP Search Tool → MCP Search Handler: invokes handler (evidence: `mcp.go`)
- Configure Credentials → Host Config: saves host (evidence: `main.go`)
- Configure Credentials → Token Keyring: saves token (evidence: `main.go`)
- CLI Commands → Host Config: loads host (evidence: `main.go`)
- CLI Commands → Token Keyring: loads token (evidence: `main.go`)
- MCP Server → Host Config: loads host (evidence: `mcp.go`)
- MCP Server → Token Keyring: loads token (evidence: `mcp.go`)
- CLI Search → Search Jobs: creates job (evidence: `main.go`)
- CLI Search → Search Status: polls status (evidence: `main.go`)
- CLI Search → Search Results: fetches results (evidence: `main.go`)
- MCP Search Handler → Search Jobs: creates job (evidence: `mcp.go`)
- MCP Search Handler → Search Status: polls status (evidence: `mcp.go`)
- MCP Search Handler → Search Results: fetches results (evidence: `mcp.go`)
- Search Jobs → Splunk Instance: submits search (evidence: `internal/splunk/client.go`)
- Search Status → Splunk Instance: queries status (evidence: `internal/splunk/client.go`)
- Search Results → Splunk Instance: fetches results (evidence: `internal/splunk/client.go`)
- Saved Searches → Splunk Instance: manages searches (evidence: `internal/splunk/client.go`)
- Scheduled Alerts → Splunk Instance: lists alerts (evidence: `internal/splunk/client.go`)
- Server Info → Splunk Instance: queries info (evidence: `internal/splunk/client.go`)
- Event Collector → Splunk Instance: sends events (evidence: `internal/splunk/client.go`)
