# cloudfoundry/cli architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source, monolithic CLI tool written in Go (the Cloud Foundry CLI).
- It implements two major versions (v7 and v8) of Cloud Foundry API clients, a plugin API, command parsing, and local configuration/state persistence.

##### High-level architectural layers
a. Presentation / Entrypoint
- main.go → CLI initialization, reads flags, invokes the command loader
- command loader / parser (cf/commandsloader, cf/flagcontext, util/command_parser)
b. Command Registry & Handlers
- cf/commandregistry & cf/commands/v7 + cf/commands (core commands)
- Implements the Command Pattern: each command is a struct with `Execute()`
c. Actor Layer (Business Logic)
- actor/sharedaction: reusable plumbing (auth, help, target checking)
- actor/v7action & actor/v7pushaction: core push/poll/start/stop logic against CF API
- actor/pluginaction: install/uninstall plugins
- actor/cfnetworkingaction: network policy operations
d. API Client Layer
- api/cloudcontroller (v2 & ccv3), api/uaa, api/router, api/logcache, api/plugin
- Wrap raw HTTP, handle authentication, versioning, error conversion
e. Transport & Helpers
- cf/net & api/*/wrapper: HTTP client, retries, trace headers, request logging
f. Configuration & Persistence
- cf/configuration & util/configv3: read/write ~/.cf/config.json, plugin configs
- manifest & .cfignore parsing (cf/manifest, util/manifestparser)
g. Output / UI
- cf/trace: logging/tracing to stdout or file
- i18n: localization via JSON resource files
h. Plugins Subsystem
- plugin/shim & plugin/rpc: RPC‐based plugin protocol, `cf plugin install`
- plugin/cli_connection: in‐process plugin invocation
i. External Systems
- Cloud Foundry CC API endpoints (v2/v3), UAA auth, Routing API, Log Cache
- Local disk for config and plugin binaries
- SSH subsystem (cf/ssh, util/clissh)

##### Relationships & data flow
- User → Terminal → main.go → command parser → command registry
- From a command `Execute()` → Actor layer (shared / v7 / plugin actor)
- Actors call API Client layer → HTTP Transport → Cloud Foundry back-end services
- Responses flow back up: HTTP → API client → Actor → Command → UI → User
- Configuration reads/writes happen at startup or by specific commands (e.g., `cf config`)
- Plugin commands are discovered/loaded at startup; calls go through shim → RPC server → plugin process

##### Architectural patterns & principles
- Command Pattern for extensible CLI commands
- Actor (Service) Layer to encapsulate business logic, isolate from HTTP details
- Adapter/Wrapper around HTTP clients for retry, auth, trace
- Plugin API via RPC for external extension
- Strict separation of concerns: parsing, business logic, transport, UI, config

##### Technologies & frameworks
- Go modules (go.mod), standard library + minimal external deps
- ginkgo/gomega for testing (numerous `_test.go` suites)
- JSON‐based i18n and CLI‐help templates
- Makefile, GitHub Actions workflows for build/test/release

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::external

    subgraph "Presentation / Entrypoint"
        Main["main.go"]:::coreBlue
        CmdLoader["Command Loader\n(cf/commandsloader)"]:::coreBlue
        FlagContext["Flag Context\n(cf/flagcontext)"]:::coreBlue
        Parser["Command Parser\n(util/command_parser)"]:::coreBlue
    end

    subgraph "Command Registry & Handlers"
        Registry["Command Registry\n(cf/commandregistry)"]:::coreBlue
        CoreCmds8["Core Commands v8\n(cf/commands/)"]:::coreBlue
        CoreCmds7["Core Commands v7\n(command/v7/)"]:::coreBlue
    end

    subgraph "Actor Layer\n(Business Logic)"
        SharedAct["Shared Action\n(actor/sharedaction)"]:::actorGreen
        V7Act["v7 Action\n(actor/v7action)"]:::actorGreen
        V7Push["v7 Push Action\n(actor/v7pushaction)"]:::actorGreen
        PluginAct["Plugin Action\n(actor/pluginaction)"]:::actorGreen
        NetAct["Networking Action\n(actor/cfnetworkingaction)"]:::actorGreen
    end

    subgraph "API Client Layer"
        CC2["CloudController v2\n(api/cloudcontroller)"]:::clientOrange
        CC3["CloudController v3\n(api/cloudcontroller/ccv3)"]:::clientOrange
        UAA["UAA Client\n(api/uaa)"]:::clientOrange
        Router["Router API\n(api/router)"]:::clientOrange
        LogCache["Log Cache\n(api/logcache)"]:::clientOrange
        PluginAPI["Plugin API\n(api/plugin)"]:::clientOrange
    end

    subgraph "Transport & Helpers"
        HTTP["HTTP Client\n(cf/net)"]:::utilGrey
        RetryCC["CC Retry Wrapper\n(api/cloudcontroller/wrapper)"]:::utilGrey
        RetryUAA["UAA Retry Wrapper\n(api/uaa/wrapper)"]:::utilGrey
        ReqLog["Plugin Request Logger\n(api/plugin/wrapper)"]:::utilGrey
    end

    subgraph "Configuration & Persistence"
        ConfigDisk["Config Persistor\n(cf/configuration)"]:::utilGrey
        ConfigV3["Config v3\n(util/configv3)"]:::utilGrey
        Manifest["Manifest Parser\n(cf/manifest)"]:::utilGrey
        ManifestParse["Manifest Locator\n(util/manifestparser)"]:::utilGrey
    end

    subgraph "Output / UI"
        UI["Terminal UI\n(cf/terminal)"]:::utilGrey
        Trace["Trace Logger\n(cf/trace)"]:::utilGrey
        I18n["I18n\n(cf/i18n)"]:::utilGrey
    end

    subgraph "Plugins Subsystem"
        Shim["Plugin Shim\n(plugin/shim)"]:::pluginPurple
        CliConn["CLI Connection\n(plugin/cli_connection)"]:::pluginPurple
        RPC["RPC Server\n(plugin/rpc)"]:::pluginPurple
    end

    subgraph "SSH Subsystem"
        SSH["SSH\n(cf/ssh)"]:::utilGrey
        CliSSH["CLI SSH\n(util/clissh)"]:::utilGrey
    end

    subgraph "External Systems"
        CloudAPI["Cloud Controller API"]:::external
        UAAExt["UAA Auth Service"]:::external
        RouterExt["Routing API"]:::external
        LogCacheExt["Log Cache Service"]:::external
        Disk["Local Disk"]:::external
        SSHSub["OS SSH"]:::external
    end

    %% Data Flow
    User -->|"input"| Main
    Main -->|"load commands"| CmdLoader
    CmdLoader --> Parser
    Parser --> Registry
    Registry --> CoreCmds8
    Registry --> CoreCmds7
    Registry --> Shim
    Shim --> RPC
    RPC --> CliConn

    Registry --> ConfigDisk
    Parser --> Manifest

    CoreCmds8 --> SharedAct
    CoreCmds7 --> SharedAct

    SharedAct --> V7Act
    SharedAct --> V7Push
    SharedAct --> PluginAct
    SharedAct --> NetAct
    SharedAct --> SSHSub

    V7Act --> CC2
    V7Act --> CC3
    V7Push --> CC2
    PluginAct --> PluginAPI
    NetAct --> Router
    NetAct --> LogCache

    CC2 --> HTTP
    CC3 --> HTTP
    UAA --> HTTP
    Router --> HTTP
    LogCache --> HTTP
    PluginAPI --> HTTP

    HTTP --> CloudAPI
    HTTP --> UAAExt
    HTTP --> RouterExt
    HTTP --> LogCacheExt

    ConfigDisk --> Disk
    Manifest --> Disk

    UI --> User
    Trace --> User

    %% Click Events
    click Main "https://github.com/cloudfoundry/cli/blob/main/./main.go"
    click CmdLoader "https://github.com/cloudfoundry/cli/blob/main/./cf/commandsloader/commands_loader.go"
    click FlagContext "https://github.com/cloudfoundry/cli/blob/main/./cf/flagcontext/flag_content_helper.go"
    click Parser "https://github.com/cloudfoundry/cli/blob/main/./util/command_parser/command_parser.go"
    click Registry "https://github.com/cloudfoundry/cli/blob/main/./cf/commandregistry/registry.go"
    click CoreCmds8 "https://github.com/cloudfoundry/cli/tree/main/./cf/commands/"
    click CoreCmds7 "https://github.com/cloudfoundry/cli/tree/main/./command/v7/"
    click SharedAct "https://github.com/cloudfoundry/cli/blob/main/./actor/sharedaction/actor.go"
    click V7Act "https://github.com/cloudfoundry/cli/blob/main/./actor/v7action/actor.go"
    click V7Push "https://github.com/cloudfoundry/cli/blob/main/./actor/v7pushaction/actor.go"
    click PluginAct "https://github.com/cloudfoundry/cli/blob/main/./actor/pluginaction/actor.go"
    click NetAct "https://github.com/cloudfoundry/cli/blob/main/./actor/cfnetworkingaction/actor.go"
    click CC2 "https://github.com/cloudfoundry/cli/blob/main/./api/cloudcontroller/client.go"
    click CC3 "https://github.com/cloudfoundry/cli/blob/main/./api/cloudcontroller/ccv3/client.go"
    click UAA "https://github.com/cloudfoundry/cli/blob/main/./api/uaa/client.go"
    click Router "https://github.com/cloudfoundry/cli/blob/main/./api/router/client.go"
    click LogCache "https://github.com/cloudfoundry/cli/blob/main/./api/logcache/log_cache_client.go"
    click PluginAPI "https://github.com/cloudfoundry/cli/blob/main/./api/plugin/client.go"
    click HTTP "https://github.com/cloudfoundry/cli/blob/main/./cf/net/http_client.go"
    click RetryCC "https://github.com/cloudfoundry/cli/blob/main/./api/cloudcontroller/wrapper/retry_request.go"
    click RetryUAA "https://github.com/cloudfoundry/cli/blob/main/./api/uaa/wrapper/retry_request.go"
    click ReqLog "https://github.com/cloudfoundry/cli/blob/main/./api/plugin/wrapper/request_logger.go"
    click ConfigDisk "https://github.com/cloudfoundry/cli/blob/main/./cf/configuration/config_disk_persistor.go"
    click ConfigV3 "https://github.com/cloudfoundry/cli/blob/main/./util/configv3/config.go"
    click Manifest "https://github.com/cloudfoundry/cli/blob/main/./cf/manifest/manifest.go"
    click ManifestParse "https://github.com/cloudfoundry/cli/blob/main/./util/manifestparser/locator.go"
    click UI "https://github.com/cloudfoundry/cli/blob/main/./cf/terminal/ui.go"
    click Trace "https://github.com/cloudfoundry/cli/blob/main/./cf/trace/trace.go"
    click I18n "https://github.com/cloudfoundry/cli/blob/main/./cf/i18n/i18n.go"
    click Shim "https://github.com/cloudfoundry/cli/blob/main/./plugin/plugin_shim.go"
    click CliConn "https://github.com/cloudfoundry/cli/blob/main/./plugin/cli_connection.go"
    click RPC "https://github.com/cloudfoundry/cli/blob/main/./plugin/rpc/cli_rpc_server.go"
    click SSH "https://github.com/cloudfoundry/cli/blob/main/./cf/ssh/ssh.go"
    click CliSSH "https://github.com/cloudfoundry/cli/blob/main/./util/clissh/secure_client.go"

    %% Styles
    classDef coreBlue fill:#cce5ff,stroke:#004085,color:#004085
    classDef actorGreen fill:#d4edda,stroke:#155724,color:#155724
    classDef clientOrange fill:#fff3cd,stroke:#856404,color:#856404
    classDef pluginPurple fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef utilGrey fill:#f8f9fa,stroke:#6c757d,color:#343a40
    classDef external fill:#d1ecf1,stroke:#0c5460,color:#0c5460
```
