Client CLI Tool
Relevant source files
The following files were used as context for generating this wiki page:
The Client CLI Tool is a command-line interface designed for managing and interacting with the Hoop gateway and its associated infrastructure. It serves as a primary touchpoint for engineers and administrators to manage resources, inspect sessions, validate runbooks, and perform administrative tasks across various protocols including PostgreSQL, MySQL, and Kubernetes.
The CLI acts as a bridge between the local environment and the Hoop gateway, utilizing API keys or bearer tokens for authentication. It facilitates operational workflows such as resource creation, health checks, and session monitoring through a structured command hierarchy built on the Cobra library.
Sources: README.md:128-135, client/cmd/admin/admin.go:37-41, client/cmd/sessions.go:42-46
Command Architecture
The CLI follows a nested command structure where the hoop root command branches into specialized subcommands. This modularity allows for clear separation between standard user operations (like session listing) and administrative functions.
The diagram above illustrates the primary command hierarchy used to navigate the tool's functionality.
Sources: client/cmd/admin/admin.go:19-27, client/cmd/sessions.go:76-81, client/cmd/resources.go:50-108, client/cmd/runbooks/runbooks.go:44-50
Session Management
The sessions module allows users to list and inspect activity logs within the Hoop environment. It supports filtering by user, role, connection type, and review status.
Listing Sessions
The list command retrieves session data from the /api/sessions endpoint. Users can specify fields to display and choose between human-readable tables or JSON output for scripting.
| Parameter | Type | Description |
|---|---|---|
--user | String | Filter by user subject ID |
--role | String | Filter by role name |
--type | String | Filter by connection type (e.g., postgres) |
--status | String | Filter by review status (e.g., pending) |
--json | Boolean | Output as formatted JSON |
Sources: client/cmd/sessions.go:48-73, client/cmd/sessions.go:127-150
Session Details and Analysis
Individual sessions can be inspected using hoop sessions get <id>. This command provides detailed metadata, including the command script (truncated), review status, and AI-driven risk analysis.
The sequence shows the flow of fetching detailed session information including AI risk scoring.
Sources: client/cmd/sessions.go:276-302, client/cmd/sessions.go:305-412
Resource and Role Management
Resources represent the underlying infrastructure (databases, APIs, servers), while roles (often referred to as connections) define how users access those resources.
Resource Operations
Users can manage resources through the hoop resources command set. This includes creating new infrastructure entries and verifying their connectivity via health checks.
- Create: Sends a POST request to
/api/resourceswith name, type, and environment variables. - Health Check: Executes a connectivity test via
/api/resources/{name}/health.
Sources: client/cmd/resources.go:63-74, client/cmd/resources.go:100-108, client/cmd/resources.go:343-375
Connection Descriptions
The describe command provides a comprehensive view of a specific connection, merging data from the connection metadata, associated agents, and enabled plugins.
// From client/cmd/describe.go:94-110
func displayConnectionDetails(config *clientconfig.Config, conn map[string]any) {
name := toStr(conn["name"])
connType := toStr(conn["type"])
status := toStr(conn["status"])
agentID := toStr(conn["agent_id"])
allAgentInfo := fetchAllAgentInfo(config)
agentName := getAgentNameFromAllInfo(allAgentInfo, agentID)
// ...
fmt.Printf("name: %s\n", name)
fmt.Printf("type: %s\n", connType)
fmt.Printf("status: %s\n", strings.ToLower(status))
fmt.Printf("agent: %s\n", agentName)
}
Sources: client/cmd/describe.go:94-110, client/cmd/describe.go:138-164
Runbook Operations
Runbooks are parameterized templates stored in Git repositories. The CLI provides tools to list, create, and validate these templates before deployment.
Validation and Linting
The hoop runbooks lint command validates the syntax of a runbook file. It parses the template and simulates execution with provided parameters to detect errors.
- Read Input: Accepts a file path or STDIN.
- Parse: Uses the
common/runbookspackage to validate template syntax. - Execute: Simulates execution with optional
-p(parameter) flags. - Error Context: Displays the problematic code segment with highlighting if a failure occurs.
Sources: client/cmd/runbooks/runbooks.go:52-113, client/cmd/runbooks/runbooks.go:420-449
Administrative Utilities
The admin command set provides deep inspection into the gateway's state and configuration.
Server Information
The serverinfo command retrieves the gateway's version, commit hashes, authentication methods, and license details from /api/serverinfo.
| Field | Description |
|---|---|
Tenant Type | The tenancy model of the gateway |
IDP Provider | Configured identity provider (e.g., OIDC) |
License Key ID | The unique identifier for the current license |
Valid | Boolean indicating if the license is currently active |
Sources: client/cmd/admin/admin.go:61-82, client/cmd/admin/admin.go:111-137
Resource Inspection
The hoop admin get command provides a "tabview" for various system resources. It supports a wide range of types including agents, plugins, users, and spiffe-mappings. It often makes multiple API calls to enrich data, such as resolving agent names for connections.
Sources: client/cmd/admin/get.go:50-61, client/cmd/admin/get.go:106-135, client/cmd/admin/get.go:217-238
Conclusion
The Client CLI Tool is a versatile utility for managing the lifecycle of production access. By providing structured commands for session auditing, resource configuration, and runbook validation, it ensures that infrastructure operations are both visible and governed according to the gateway's security policies.