A Swift CLI and interactive TUI for App Store Connect, built for agent-first use on a clean three-layer architecture.
The primary consumer of this CLI is an AI agent, not a human typing at a shell. This shapes every design decision:
| Concern | Human CLI | Agent CLI (this project) |
|---|---|---|
| Output format | Pretty tables | JSON (default) |
| Errors | Readable prose | Structured JSON |
| Field coverage | Display-friendly subset | Complete — agents read everything |
| Response content | Data only | Data + what to do next |
| Enum values | Display names | Raw API strings + semantic booleans |
| Parent IDs | Implied by context | Explicit in every response |
Domain models are complete and semantic — not display-optimised. Every model:
- Carries its parent ID so agents can correlate responses without re-querying
- Exposes semantic boolean properties that agents use for decisions (
isLive,isEditable,isPending,isComplete) - Uses raw API enum strings as the Codable representation for stability
// Agents can answer "should I submit this version?" without extra calls:
version.isEditable // true when state allows editing
version.isPending // true when waiting on Apple — agent should wait, not act
version.isLive // true when on the App Store
Commands mirror the App Store Connect API hierarchy exactly:
App
└── AppStoreVersion (platform: iOS/macOS/tvOS/watchOS/visionOS)
└── AppStoreVersionLocalization (locale: en-US, zh-Hans, …)
└── AppScreenshotSet (displayType: iPhone 6.7", iPad 12.9", …)
└── AppScreenshot
Each level has its own command:
asc apps list
asc versions list --app-id <id>
asc version-localizations list --version-id <id>
asc screenshot-sets list --localization-id <id>
asc screenshots list --set-id <id>
Command Affordances is this project's CLI equivalent of REST HATEOAS.
In REST, HATEOAS (Hypermedia as the Engine of Application State) embeds URLs in responses so clients can navigate without knowing the API structure upfront. In CLI, Command Affordances embeds ready-to-run commands in responses so agents can navigate without memorising the command tree.
| REST HATEOAS | CLI Command Affordances |
|---|---|
Embeds _links with URLs |
Embeds affordances with CLI commands |
| Client follows a URL | Agent executes a command |
| Drives HTTP state transitions | Drives CLI navigation |
An agent calls asc versions list --app-id app-abc and receives:
{
"data": [
{
"id": "v1",
"appId": "app-abc",
"versionString": "2.1.0",
"platform": "IOS",
"state": "READY_FOR_SALE",
"isLive": true,
"isEditable": false,
"isPending": false,
"affordances": {
"listLocalizations": "asc version-localizations list --version-id v1",
"listVersions": "asc versions list --app-id app-abc"
}
}
]
}The agent reads affordances.listLocalizations and executes it directly — no command-tree knowledge required.
- Self-describing — the response tells the agent what it can do next
- State-aware — affordances reflect the resource's current state (e.g.
submitonly appears whenisEditable == true) - Copy-paste ready — values are literal CLI strings that work immediately
Affordances is a protocol that domain-layer response types adopt. Each resource computes its own affordances from its ID fields and state:
protocol AffordanceProviding {
var affordances: [String: String] { get }
}
extension AppStoreVersion: AffordanceProviding {
var affordances: [String: String] {
var cmds = [
"listLocalizations": "asc version-localizations list --version-id \(id)",
"listVersions": "asc versions list --app-id \(appId)",
]
if isEditable {
cmds["submitForReview"] = "asc versions submit --version-id \(id)"
}
return cmds
}
}Sources/
├── ASCKit/<Concept>/ # public face: rich models, state enums, affordances, @Mockable repositories (zero I/O)
│ └── Internal/ # implementations: SDK adapters (appstoreconnect-swift-sdk), DTO mapping, auth providers
│ └── System/ # only the bare outside call, ≤100 lines
└── ASCCommand/ # CLI executable + TUI: argument parsing, output formatting, interactive UI
Import flow: ASCCommand -> ASCKit. One folder per App Store Connect concept
(ASCKit/Apps/Builds/, ASCKit/Auth/, …), each with its public face at the
top and its implementations in Internal/. The layout and its rules:
concept-folders design.
Key model design rules:
- Every model carries its parent ID (e.g.
AppStoreVersion.appId,AppScreenshot.setId). The App Store Connect API does not include parent IDs in response bodies, so theInternal/mappers inject them from the request parameter. - State enums expose semantic booleans (
isLive,isEditable,isPending,isComplete) - All models are
Sendable,Equatable,Codable— the JSON encoding IS the public schema
asc
├── apps list # List apps
├── versions list --app-id <id> # List App Store versions (per platform)
├── localizations list --version-id <id> # List localizations for a version
├── screenshot-sets list --localization-id <id> # List screenshot sets
├── screenshots list --set-id <id> # List screenshots in a set
├── builds list [--app-id <id>] # List builds
├── testflight
│ ├── groups [--app-id <id>] # List beta groups
│ └── testers [--group-id <id>] # List beta testers
├── auth check # Verify credentials
├── version # Print version
└── tui # Launch interactive TUI
Key files:
ASC.swift—@mainentry point, registers all subcommandsGlobalOptions.swift—--output,--pretty,--timeoutflags (default output: JSON)OutputFormatter.swift— JSON / table / markdown renderingClientProvider.swift— Factory for authenticated repository instances
Interactive terminal UI built with TauTUI. Purely a presentation layer — reuses the same ASCKit repositories as the CLI.
Navigation follows the real App Store Connect resource hierarchy:
Main Menu
├── Apps List
│ └── App Menu (Info | Screenshots)
│ └── Screenshots → Version List (iOS 2.1.0 / macOS 1.5.0 / …)
│ └── Localization List (en-US / zh-Hans / …) [auto-skips if one locale]
│ └── Screenshot Sets List (iPhone 6.7" / iPad 12.9" / …)
│ └── Screenshots (filename, size, state)
├── Builds List → Build Detail
└── TestFlight Menu → Beta Groups / Beta Testers
Chicago School TDD — state-based, not interaction-based. Tests verify what domain objects return and compute, not how they call collaborators.
Tests/
├── ASCKitTests/ # mirrors Sources/ASCKit/ folder for folder — <Concept>/ and <Concept>/Internal/
│ └── TestHelpers/ # MockRepositoryFactory
└── ASCCommandTests/ # commands and REST routes, asserting the full output
Test naming: backtick style (func \version is live when state is readyForSale`()). Mocking: @Mockable+given().willReturn()`.
| Package | Purpose |
|---|---|
| appstoreconnect-swift-sdk | Type-safe App Store Connect API client |
| swift-argument-parser | CLI argument parsing |
| Mockable | Protocol mocking for tests |
| TauTUI | Component-based terminal UI framework |
| Variable | Purpose |
|---|---|
ASC_KEY_ID |
API key ID |
ASC_ISSUER_ID |
Issuer ID |
ASC_PRIVATE_KEY_PATH |
Path to .p8 private key file |