# linuxfoundation/lfx-cli architecture

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

- Interactive diagram: https://gitdiagram.com/linuxfoundation/lfx-cli
- Repository: https://github.com/linuxfoundation/lfx-cli

## Overview

LFX CLI turns terminal commands into authenticated platform operations. The main workflow is login through Auth0, persist credentials and environment state, resolve an access token, then call either a raw API endpoint or a typed Query Service endpoint and print the response. Separate command modules also expose authentication status, logout, environment/backend discovery, and response filtering. The sampled files show command registration and key calls; some service-runner and token-resolution internals are not fully excerpted, so uncertain links are omitted.

Main entry points: [`cmd/lfx/main.go`](https://github.com/linuxfoundation/lfx-cli/blob/main/cmd/lfx/main.go) (CLI command router), [`internal/commands/auth.go`](https://github.com/linuxfoundation/lfx-cli/blob/main/internal/commands/auth.go) (Auth commands), [`internal/commands/api.go`](https://github.com/linuxfoundation/lfx-cli/blob/main/internal/commands/api.go) (Raw API command), [`internal/commands/query.go`](https://github.com/linuxfoundation/lfx-cli/blob/main/internal/commands/query.go) (Query service commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI entry"]
  node_entry["CLI command router<br/>[main.go]"]
  node_terminal["Safe terminal output<br/>[terminal.go]"]
  node_docscommand["Command reference output<br/>[docs.go]"]
end

subgraph group_auth["Authentication"]
  node_authcmd["Auth commands<br/>[auth.go]"]
  node_environment["Environment selection<br/>[environment.go]"]
end

subgraph group_requests["Platform requests"]
  node_rawapi["Raw API command<br/>[api.go]"]
  node_querycmd["Query service commands<br/>[query.go]"]
  node_goarunner["Goa endpoint runner<br/>[goa.go]"]
end

subgraph group_storage["Credential storage"]
  node_credstore[("Credential store<br/>[credstore.go]")]
end

node_developer(("Developer"))
node_auth0["Auth0"]
node_oskeychain[("OS credential backends")]
node_lfxapi["LFX platform APIs"]
node_queryservice["Query Service"]

node_developer -->|"runs commands"| node_entry
node_entry -->|"registers"| node_authcmd
node_entry -->|"registers"| node_rawapi
node_entry -->|"registers"| node_querycmd
node_entry -->|"registers"| node_docscommand
node_authcmd -->|"authenticates with"| node_auth0
node_authcmd -->|"loads and saves"| node_credstore
node_authcmd -->|"selects environment"| node_environment
node_credstore -->|"uses credential backends"| node_oskeychain
node_rawapi -->|"sends authenticated requests"| node_lfxapi
node_rawapi -->|"writes responses"| node_terminal
node_querycmd -.->|"configures endpoints"| node_goarunner
node_goarunner -.->|"dispatches requests"| node_queryservice
node_querycmd -->|"uses logged-in environment"| node_lfxapi

click node_entry "https://github.com/linuxfoundation/lfx-cli/blob/main/cmd/lfx/main.go"
click node_authcmd "https://github.com/linuxfoundation/lfx-cli/blob/main/internal/commands/auth.go"
click node_environment "https://github.com/linuxfoundation/lfx-cli/blob/main/internal/commands/environment.go"
click node_credstore "https://github.com/linuxfoundation/lfx-cli/blob/main/internal/credstore/credstore.go"
click node_rawapi "https://github.com/linuxfoundation/lfx-cli/blob/main/internal/commands/api.go"
click node_querycmd "https://github.com/linuxfoundation/lfx-cli/blob/main/internal/commands/query.go"
click node_goarunner "https://github.com/linuxfoundation/lfx-cli/blob/main/internal/commands/goa.go"
click node_terminal "https://github.com/linuxfoundation/lfx-cli/blob/main/internal/commands/terminal.go"
click node_docscommand "https://github.com/linuxfoundation/lfx-cli/blob/main/internal/commands/docs.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_entry,node_terminal,node_docscommand toneBlue
class node_authcmd,node_environment,node_oskeychain toneAmber
class node_rawapi,node_querycmd,node_goarunner,node_lfxapi toneMint
class node_credstore toneRose
class node_developer,node_auth0,node_queryservice toneIndigo
```

## Components

### CLI entry

- [CLI command router](https://github.com/linuxfoundation/lfx-cli/blob/main/cmd/lfx/main.go): `cmd/lfx/main.go`
- [Safe terminal output](https://github.com/linuxfoundation/lfx-cli/blob/main/internal/commands/terminal.go): `internal/commands/terminal.go`
- [Command reference output](https://github.com/linuxfoundation/lfx-cli/blob/main/internal/commands/docs.go): `internal/commands/docs.go`

### Authentication

- [Auth commands](https://github.com/linuxfoundation/lfx-cli/blob/main/internal/commands/auth.go): `internal/commands/auth.go`
- [Environment selection](https://github.com/linuxfoundation/lfx-cli/blob/main/internal/commands/environment.go): `internal/commands/environment.go`

### Platform requests

- [Raw API command](https://github.com/linuxfoundation/lfx-cli/blob/main/internal/commands/api.go): `internal/commands/api.go`
- [Query service commands](https://github.com/linuxfoundation/lfx-cli/blob/main/internal/commands/query.go): `internal/commands/query.go`
- [Goa endpoint runner](https://github.com/linuxfoundation/lfx-cli/blob/main/internal/commands/goa.go): `internal/commands/goa.go`

### Credential storage

- [Credential store](https://github.com/linuxfoundation/lfx-cli/blob/main/internal/credstore/credstore.go): `internal/credstore/credstore.go`

### Other components

- **Developer**
- **Auth0**
- **OS credential backends**
- **LFX platform APIs**
- **Query Service**

## Connections

- Developer → CLI command router: runs commands (evidence: `README.md`)
- CLI command router → Auth commands: registers (evidence: `cmd/lfx/main.go`)
- CLI command router → Raw API command: registers (evidence: `cmd/lfx/main.go`)
- CLI command router → Query service commands: registers (evidence: `cmd/lfx/main.go`)
- CLI command router → Command reference output: registers (evidence: `cmd/lfx/main.go`)
- Auth commands → Auth0: authenticates with (evidence: `README.md`)
- Auth commands → Credential store: loads and saves (evidence: `internal/commands/auth.go`)
- Auth commands → Environment selection: selects environment (evidence: `README.md`)
- Credential store → OS credential backends: uses credential backends (evidence: `internal/credstore/credstore.go`)
- Raw API command → LFX platform APIs: sends authenticated requests (evidence: `README.md`)
- Raw API command → Safe terminal output: writes responses (evidence: `internal/commands/api.go`)
- Query service commands → Goa endpoint runner: configures endpoints
- Goa endpoint runner → Query Service: dispatches requests
- Query service commands → LFX platform APIs: uses logged-in environment (evidence: `README.md`)
