og-cli: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

og is a CLI tool (binary name: og) for the OpenGate IoT platform REST API by Amplía Soluciones. Built in Go with Cobra (commands), Viper (config), and Bubble Tea + Lip Gloss (interactive TUI).

Commands

task build          # build the og binary
task test           # go test ./... -v
task lint           # golangci-lint run ./...
task fmt            # gofmt + goimports
task tidy           # go mod tidy
task install        # go install with ldflags
go test ./internal/client/ -run TestLogin -v   # run a single test

Version info is injected via ldflags — see Taskfile.yml LDFLAGS.

Architecture

main.go              → cmd.Execute()
cmd/                 → Cobra commands (root, login, version, mcp, datamodels, devices)
pkg/opengate/        → OpenGate REST API client (HTTP methods, auth, resource methods)
pkg/query/           → Search filter parser (-w "field op value", query strings)
internal/config/     → Viper config, profiles, .env loading
internal/mcp/        → MCP server (stdio + HTTP transports) + tool definitions
internal/output/     → JSON/table output formatting
internal/tui/        → Bubble Tea interactive TUI
internal/unwrap/     → Workspace/rule/connector unwrap to local dirs
internal/views/      → Named field views for searches

pkg/ is the public library surface: it is consumed by external services (e.g. Punto de Luz), so its API is a contract. internal/ is CLI-private.

Library conventions for pkg/:

• Every method that performs I/O takes ctx context.Context as its first parameter, propagated to http.NewRequestWithContext. No exceptions.
• Per-client configuration goes through functional options on New (WithHTTPClient, WithTLS, WithAPIVersion, WithAPIKey) — never process-wide state. ConfigureTLS/NewHTTPClient are deprecated leftovers kept for the CLI, which has exactly one endpoint per invocation.
• North API path constants carry the {v} version placeholder, resolved per client. Never hardcode a version segment.
• A misconfigured client is not a panic and not a second constructor: New records the error, and Err() plus every request return it.
• A typed getter is lossy by construction. Most families return json.RawMessage and pass the platform's bytes through; datamodels, datasets, timeseries and workspaces decode into structs, so any field the struct does not name is dropped without a word. Where a struct exists, ship a …Raw sibling (GetDatamodelRaw, GetDatasetRaw, GetTimeSeriesRaw, ListTimeSeriesRaw, GetWorkspaceRaw) so callers who need fidelity are not hostage to this package being current — and surface it as --raw on the CLI get. Note og workspace pull reads through the struct too, so workspaces are the one family whose pull is not a passthrough.