Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
208 commits
Select commit Hold shift + click to select a range
0788e4c
docs: capture fctl v4 architecture plan
flemzord May 14, 2026
6e5b310
docs: add v4 implementation goals
flemzord May 14, 2026
beb91d7
feat: add isolated v4 cli skeleton
flemzord May 14, 2026
b8e37ff
docs: track v4 todo status
flemzord May 14, 2026
378edcf
feat: add v4 context config package
flemzord May 14, 2026
506e468
feat: add v4 credential store abstractions
flemzord May 14, 2026
b030fca
feat: add v4 capabilities model
flemzord May 14, 2026
dd55ac6
feat: add v4 runtime shell
flemzord May 14, 2026
80cc115
docs: mark v4 foundation goal complete
flemzord May 14, 2026
846c40a
feat: add v4 context commands
flemzord May 14, 2026
e1f460f
docs: mark v4 context goal complete
flemzord May 14, 2026
6304dee
feat: add v4 auth providers
flemzord May 14, 2026
e6ea0b6
feat: wire auth into v4 runtime
flemzord May 14, 2026
a307e0f
docs: mark v4 auth goal complete
flemzord May 14, 2026
ec5dde8
feat: add capabilities manifest generator
flemzord May 14, 2026
7b86175
feat: generate initial capabilities manifest
flemzord May 14, 2026
50a32ed
docs: mark capabilities manifest goal complete
flemzord May 14, 2026
96487c1
feat: add api version resolver
flemzord May 14, 2026
91bab20
feat: resolve api versions in runtime
flemzord May 14, 2026
25715dd
docs: mark api resolver goal complete
flemzord May 14, 2026
46cca82
feat: add v4 target inspect command
flemzord May 14, 2026
5a068cd
docs: mark target inspect goal complete
flemzord May 14, 2026
6954051
feat: add ledger transaction list service
flemzord May 14, 2026
bac6423
feat: wire v4 ledger transaction list command
flemzord May 14, 2026
75ebe96
docs: mark first ledger command goal complete
flemzord May 14, 2026
3fe30f2
feat: add v3 migration planner
flemzord May 14, 2026
e66c415
feat: add v3 migration command
flemzord May 14, 2026
e13b88e
docs: mark v3 migration goal complete
flemzord May 14, 2026
81db37d
feat: add structured yaml output
flemzord May 14, 2026
dc5c1fc
test: add v4 cli integration coverage
flemzord May 14, 2026
47970d5
test: cover v4 cli error paths
flemzord May 14, 2026
a7bafb2
docs: mark integration hardening goal complete
flemzord May 14, 2026
6e5c306
docs: add v4 cutover plan
flemzord May 14, 2026
d329e30
docs: mark v4 roadmap goals complete
flemzord May 14, 2026
614e0bb
docs: add v3 to v4 migration plan
flemzord May 14, 2026
e3c0be2
docs: update v4 migration command mapping
flemzord May 14, 2026
48dfebb
docs: record v4 migration decisions
flemzord May 14, 2026
f4775ad
test: add v3 command inventory fixture
flemzord May 14, 2026
f8d40c4
feat: canonicalize ledger source filters
flemzord May 14, 2026
454a68a
feat: add v4 ledger list command
flemzord May 14, 2026
a7fb077
feat: add v4 ledger stats command
flemzord May 14, 2026
b4cf366
feat: add v4 ledger info command
flemzord May 14, 2026
89388fc
feat: add v4 ledger account commands
flemzord May 14, 2026
6d56bb6
feat: add v4 ledger transaction show command
flemzord May 14, 2026
5a81c25
feat: add v4 ledger volumes list command
flemzord May 14, 2026
725f7e1
docs: record v4 migration naming decisions
flemzord May 14, 2026
c0a1494
feat: add v4 ledger transaction revert command
flemzord May 14, 2026
d555a2f
feat: add v4 ledger transaction count command
flemzord May 14, 2026
8305253
feat: add v4 ledger transaction metadata commands
flemzord May 14, 2026
644796f
feat: add v4 ledger account metadata commands
flemzord May 14, 2026
82876b0
feat: add v4 ledger create command
flemzord May 14, 2026
3309e23
feat: add v4 ledger metadata commands
flemzord May 14, 2026
94b9874
feat: add v4 ledger transaction send command
flemzord May 14, 2026
7adc090
feat: add v4 ledger export command
flemzord May 14, 2026
ec179f7
feat: add v4 ledger import command
flemzord May 14, 2026
5047cd2
feat: add v4 ledger schema commands
flemzord May 14, 2026
1a23e3d
feat: extend v4 ledger transaction filters
flemzord May 14, 2026
94fe462
feat: support deprecated v4 ledger send positionals
flemzord May 14, 2026
e0dbead
feat: add v4 payments account commands
flemzord May 14, 2026
d0c115a
feat: add v4 payments account balances
flemzord May 14, 2026
f5e4887
feat: add v4 payments bank account commands
flemzord May 14, 2026
b4fbd32
feat: add v4 payments payment commands
flemzord May 14, 2026
12ba09b
docs: clarify v4 migration decisions
flemzord May 14, 2026
cc62888
feat: add v4 payments pool commands
flemzord May 14, 2026
d57b7f4
feat: add v4 payments pool account commands
flemzord May 14, 2026
2c017c3
feat: add v4 payments pool balance commands
flemzord May 14, 2026
2cff36e
feat: add v4 payments task command
flemzord May 14, 2026
f4355c2
feat: add v4 payments transfer initiation reads
flemzord May 14, 2026
78c02ec
feat: add v4 payments transfer initiation actions
flemzord May 14, 2026
63a6aa6
feat: add v4 payments transfer initiation status
flemzord May 14, 2026
88883b1
feat: add v4 payments transfer initiation reverse
flemzord May 14, 2026
c5f6885
feat: add v4 payments transfer initiation create
flemzord May 14, 2026
0b25f8b
feat: add v4 payments account creation
flemzord May 14, 2026
b482f7c
feat: add v4 payments bank account creation
flemzord May 14, 2026
643a5e3
feat: add v4 payments bank account actions
flemzord May 14, 2026
4fc34ac
feat: add v4 payments metadata updates
flemzord May 14, 2026
f9f862c
feat: add v4 payments creation
flemzord May 14, 2026
0fcd10e
feat: add v4 payments connector list and uninstall
flemzord May 14, 2026
e4d5db3
feat: add v4 payments connector config commands
flemzord May 14, 2026
9fb1c4e
feat: add v4 payments pool creation
flemzord May 14, 2026
eb96e90
feat: add v4 payments versions command
flemzord May 14, 2026
7e9d7aa
feat: add v4 wallet management commands
flemzord May 14, 2026
556c91d
feat: add explicit v4 wallet movements
flemzord May 14, 2026
cd39271
feat: add v4 wallet balance commands
flemzord May 14, 2026
a00bfd1
feat: add v4 wallet hold commands
flemzord May 14, 2026
75e35ea
feat: add v4 wallet transaction listing
flemzord May 14, 2026
bf1816c
feat: add v4 flows workflow read commands
flemzord May 14, 2026
45fbd87
feat: add v4 flows workflow mutation commands
flemzord May 14, 2026
3c25aa1
feat: add v4 flows instance read commands
flemzord May 14, 2026
182f8e9
feat: add v4 flows instance action commands
flemzord May 14, 2026
fbadcf3
feat: add v4 flows trigger commands
flemzord May 14, 2026
94be762
feat: add v4 flows trigger occurrence listing
flemzord May 14, 2026
b753376
feat: add v4 reconciliation read commands
flemzord May 14, 2026
3b6853a
feat: add v4 reconciliation policy mutations
flemzord May 14, 2026
f6d9033
feat: add v4 auth read commands
flemzord May 14, 2026
ca63f6a
feat: add v4 auth client mutations
flemzord May 14, 2026
7e9c0bf
feat: add v4 webhooks commands
flemzord May 14, 2026
72c2d21
docs: add v4 migration reference
flemzord May 14, 2026
1efcc98
feat: add v4 setup guidance command
flemzord May 14, 2026
170ea22
feat: add v4 cloud context commands
flemzord May 14, 2026
4bb46c6
docs: align v4 migration alias decisions
flemzord May 14, 2026
0b84411
feat: add v4 cloud read commands
flemzord May 14, 2026
bcbddf9
feat: add v4 cloud stack read commands
flemzord May 14, 2026
5dbdae7
feat: add v4 cloud stack mutations
flemzord May 14, 2026
21c9b90
feat: add v4 cloud stack users and modules
flemzord May 14, 2026
35f6c97
feat: add v4 cloud organization mutations
flemzord May 14, 2026
c2f93f0
feat: add v4 context rename and delete
flemzord May 14, 2026
ba8c035
feat: add v4 profiles context alias
flemzord May 14, 2026
a3cd11d
feat: add v4 cloud invitation commands
flemzord May 14, 2026
819436d
feat: add v4 cloud organization invitations
flemzord May 14, 2026
dd6527f
feat: add v4 cloud organization users
flemzord May 14, 2026
b6cca86
feat: add v4 cloud organization policies
flemzord May 14, 2026
d8bec83
docs: record v4 command naming decisions
flemzord May 14, 2026
e388d09
feat: make cloud stacks the canonical command
flemzord May 14, 2026
145dfe2
feat: add v4 cloud regions commands
flemzord May 14, 2026
e68a659
feat: add v4 cloud organization applications
flemzord May 14, 2026
eae3046
feat: add v4 cloud authentication provider
flemzord May 14, 2026
99e58a0
feat: add v4 cloud oauth clients
flemzord May 14, 2026
7f5c5ae
feat: add v4 cloud organization history
flemzord May 14, 2026
da6852c
feat: add v4 cloud apps commands
flemzord May 14, 2026
e40eb42
feat: add v4 ledger run-script command
flemzord May 14, 2026
88aa8f4
feat: add v4 ledger account query
flemzord May 14, 2026
d3f1e67
feat: support ledger metadata files
flemzord May 14, 2026
86b28e2
feat: add v4 cloud stack history
flemzord May 14, 2026
8d68d26
feat: add cloud app archive command
flemzord May 14, 2026
91b5539
feat: add v4 target proxy
flemzord May 14, 2026
65893f3
docs: record v4 cloud command blockers
flemzord May 14, 2026
c4db510
feat: support deprecated profile flag
flemzord May 14, 2026
a86e8ee
feat: add v4 auth login commands
flemzord May 14, 2026
6441b82
feat: add v4 auth session commands
flemzord May 14, 2026
8de51cf
feat: add v4 context default aliases
flemzord May 14, 2026
dc1879b
feat: add v4 insecure tls flag
flemzord May 14, 2026
8260a42
feat: add v4 config dir short flag
flemzord May 14, 2026
a5fa872
feat: add v4 cloud ui command
flemzord May 14, 2026
111f01d
feat: add v4 debug flag
flemzord May 14, 2026
ff72013
feat: add v4 no color flag
flemzord May 14, 2026
89123f2
docs: record deferred v4 auth telemetry items
flemzord May 14, 2026
bd01191
docs: record deferred v4 quiet telemetry flags
flemzord May 14, 2026
cb96224
feat: add ledger transaction explain preflight
flemzord May 14, 2026
dc94ac8
fix: use flows name in api version help
flemzord May 14, 2026
a332d3f
feat: keep cloud auth provider positional migration
flemzord May 14, 2026
a581194
feat: add auth clients users migration alias
flemzord May 14, 2026
d026a15
feat: expose deferred cloud login migration commands
flemzord May 14, 2026
6aa8e5f
feat: add payments get-config migration alias
flemzord May 14, 2026
75e4e00
feat: support reconciliation positional timestamp alias
flemzord May 14, 2026
3809794
feat: support flows workflow positional file alias
flemzord May 14, 2026
8a2814c
docs: add v4 implementation audit
flemzord May 14, 2026
2487f6c
chore: move v4 todos into v4 directory
flemzord May 14, 2026
0790098
feat: move cli auth commands under session
flemzord May 14, 2026
fe53c0d
fix: default v3 config migration source
flemzord May 14, 2026
eb379d7
fix: make missing v4 config actionable
flemzord May 14, 2026
2e68777
fix: suggest cloud contexts for missing config
flemzord May 14, 2026
5d07ac9
feat: bootstrap default cloud session context
flemzord May 14, 2026
34b2a14
feat: default credentials to config directory
flemzord May 14, 2026
beb22f6
fix: use final fctl config directory
flemzord May 14, 2026
d8ece6c
feat: make profile the primary target selector
flemzord May 14, 2026
c445b2c
feat: add login profile UX for v4
flemzord May 14, 2026
d0234b5
fix: restore stack proxy alias
flemzord May 14, 2026
ecf3f78
fix: move ui command under cloud
flemzord May 14, 2026
1e6e717
feat: add charmbracelet login wizard
flemzord May 14, 2026
d9c3474
fix: show all login wizard choices
flemzord May 14, 2026
8e0186a
fix: restore cloud client credential scopes
flemzord May 14, 2026
116c805
fix: default cloud runtime scopes
flemzord May 14, 2026
80d5b3c
fix: render cloud stacks as table
flemzord May 14, 2026
a86e96d
refactor: render tables with lipgloss
flemzord May 14, 2026
def64ab
feat: add formance render theme
flemzord May 14, 2026
b4abb03
feat: improve ledger stack rendering
flemzord May 14, 2026
7475bc0
fix: clarify missing cloud stack errors
flemzord May 14, 2026
cd4731a
fix: resolve single cloud stack targets
flemzord May 14, 2026
46ef3ce
test(v4): defer browser device login
flemzord May 14, 2026
77a45de
fix(v4): remove static token login option
flemzord May 14, 2026
5e612e8
feat(v4): implement browser device login
flemzord May 14, 2026
e2e21b3
feat(v4): echo login wizard choices
flemzord May 14, 2026
1ede842
fix(v4): request cloud organization scopes
flemzord May 14, 2026
d36e1ba
fix(v4): scope cloud stack membership calls
flemzord May 14, 2026
95fe4a5
fix(v4): scope cloud stack resolution
flemzord May 14, 2026
122db7b
feat(v4): add stack create wizard
flemzord May 14, 2026
bdcebf8
fix(v4): sort stack version choices
flemzord May 14, 2026
9216676
feat(v4): wait for stack creation readiness
flemzord May 14, 2026
6b6d5d0
feat(v4): style stack create progress
flemzord May 14, 2026
5c01143
feat(v4): style interactive wizard
flemzord May 14, 2026
d016e9b
fix(v4): scope cloud stack commands by organization
flemzord May 14, 2026
9d4e24d
feat(v4): check stack versions for readiness
flemzord May 14, 2026
fc356f7
fix(v4): silence prompt cancellation
flemzord May 14, 2026
4633814
fix(v4): require healthy stack versions
flemzord May 14, 2026
207fd0e
feat(v4): trace http traffic in debug mode
flemzord May 14, 2026
df95655
feat(v4): show stack wait url and elapsed time
flemzord May 14, 2026
8eebf00
feat(v4): print stack url after creation
flemzord May 14, 2026
f9a92b4
fix(v4): style stack creation url
flemzord May 14, 2026
5425362
fix(v4): style stack success message
flemzord May 14, 2026
e899911
fix(v4): hide cloud apps command
flemzord May 14, 2026
4866696
feat(v4): style cloud command output
flemzord May 14, 2026
5f872cb
feat(v4): style session and context output
flemzord May 14, 2026
c6c3174
fix(v4): refresh opaque device tokens for new scopes
flemzord May 14, 2026
d7fbac0
fix(v4): use organization auth for cloud regions
flemzord May 14, 2026
8515407
feat(v4): prompt ledger create inputs
flemzord May 14, 2026
14bac43
fix(v4): scope cloud organization commands
flemzord May 14, 2026
2a0c534
fix(v4): resolve stack product commands through stack runtime
flemzord May 14, 2026
977249b
feat(v4): style stack product output
flemzord May 14, 2026
5daafb2
feat(v4): style remaining stack product renderers
flemzord May 14, 2026
ca8e65a
feat(v4): style utility command output
flemzord May 14, 2026
f60b039
feat(v4): style migration plan output
flemzord May 14, 2026
00684d9
test(v4): verify visible command help routes
flemzord May 14, 2026
c952a1b
fix(v4): fallback cloud console url
flemzord May 14, 2026
7172a72
fix(v4): hide unsupported ledger explain command
flemzord May 14, 2026
d0ba17d
fix: satisfy inventory generator lint
flemzord May 14, 2026
c04b6fe
docs(v4): update CLI behavior documentation
flemzord May 15, 2026
cbeadc7
docs(v4): document versioning ownership tradeoffs
flemzord May 15, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 65 additions & 0 deletions .codex/skills/fctl-v4-architecture/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
---
name: fctl-v4-architecture
description: Use when working on the Formance fctl v4 CLI architecture, contexts, authentication, API version resolution, compatibility manifests, command design, or migrations from fctl v3. This skill keeps future work aligned with the repository's v4 RFC and ADRs.
---

# fctl v4 Architecture Skill

Use this skill for any `fctl` v4 design or implementation work.

## Required Reading

Before changing v4 architecture or commands, read these repository files:

- `docs/rfcs/0001-fctl-v4-architecture.md`
- `docs/cli-v4/command-design.md`
- `docs/cli-v4/compatibility-manifest.md`
- `todos/01-v4-isolated-skeleton.md`

Read ADRs as needed:

- `docs/adr/0001-contexts-as-primary-target.md`
- `docs/adr/0002-auth-is-decoupled-from-cloud.md`
- `docs/adr/0003-api-version-resolution.md`
- `docs/adr/0004-cobra-thin-runtime.md`
- `docs/adr/0005-build-v4-in-isolated-directory.md`

## Core Rules

- Do not make Formance Cloud membership required for stack commands.
- Treat contexts as the primary target selector.
- Keep auth as a target-local strategy.
- Use `/versions` plus the compatibility manifest to infer supported API namespaces.
- Commands express product intent; they must not expose API versions as the primary UX.
- Keep CLI flags canonical and product-oriented; map them to version-specific SDK request fields internally.
- Keep Cobra thin. Runtime concerns belong in typed internal packages.
- Build the rewrite under `v4/` until the explicit cutover goal.
- Follow `todos/*.md` in order unless the user explicitly reprioritizes.
- Commit after each logical step.

## CLI Rendering Policy

- Human `plain` output must go through shared rendering helpers instead of writing raw strings directly to `cmd.OutOrStdout()`.
- Use `styledSuccessLine` for successful mutations, `writeStyledKeyValues` for detail views, `writeStyledRows`/`v4render.Table` for lists, `styledEmptyLine` for empty states, and `styledInfoLine` for supporting metadata such as API versions.
- Keep scriptability intact: JSON/YAML output must stay unstyled, non-TTY plain output must remain stable, and ANSI styling must only be emitted for terminal output.
- Direct writes to `cmd.OutOrStdout()` are allowed only for raw payloads such as archives, manifests, logs, or compatibility-preserving fallback paths that are explicitly tracked by tests.
- When adding or touching a command renderer, remove it from the raw-output baseline in `v4/cmd/rendering_policy_test.go` and route its output through the shared helpers.

## Implementation Shape

Prefer this package split under `v4/` during the transition:

```text
v4/cmd/ Cobra declarations only
v4/internal/runtime/ target resolution, auth, versions, API selection
v4/internal/config/ contexts, defaults, XDG paths, migrations
v4/internal/credentials/ keyring and insecure fallback
v4/internal/capabilities generated manifest and compatibility ranges
v4/internal/commands/ typed product command implementations
v4/internal/render/ table, json, yaml, markdown
v4/internal/prompt/ optional interactive flows
```

## Validation

For command behavior, prefer integration-style tests that execute real CLI commands and assert stdout, stderr, exit codes, and config files. Keep scriptability and non-interactive usage as first-class requirements.
20 changes: 20 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# fctl v4 Guidance

Before working on the next major CLI architecture, read:

- `docs/rfcs/0001-fctl-v4-architecture.md`
- `docs/cli-v4/command-design.md`
- `docs/cli-v4/compatibility-manifest.md`
- `todos/01-v4-isolated-skeleton.md`

Core rules:

- Do not couple stack commands to Formance Cloud membership.
- Treat context, target, auth, capabilities, API version, and rendering as separate concepts.
- Commands express product intent; API version selection belongs in the runtime.
- Use `/versions` plus the generated compatibility manifest to select the best supported SDK namespace.
- Keep Cobra as a thin parser/router; keep business logic in typed internal packages.
- Store credentials in a keyring when possible; keep config files free of long-lived secrets.
- Build the rewrite under `v4/` until the explicit cutover goal.
- Follow `todos/*.md` in order unless the user explicitly reprioritizes.
- Commit after each logical step when implementing v4 work.
18 changes: 18 additions & 0 deletions docs/adr/0001-contexts-as-primary-target.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# ADR 0001: Contexts Are The Primary Target Selector

Status: Accepted for v4 planning

## Context

The current profile model is centered on Formance Cloud membership. That makes stack usage depend on Cloud identity even when the user wants to talk to a local or self-hosted stack.

## Decision

Use named contexts as the primary target selector. A context describes the target endpoint, authentication method, defaults, and API version policy.

## Consequences

- Stack commands can run without Cloud membership.
- Cloud workflows remain possible through Cloud-specific context kinds.
- `--context` and `FCTL_CONTEXT` can override the current context.
- Context export/import becomes possible later.
18 changes: 18 additions & 0 deletions docs/adr/0002-auth-is-decoupled-from-cloud.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# ADR 0002: Authentication Is Decoupled From Cloud

Status: Accepted for v4 planning

## Context

The current CLI authenticates through a membership relying party. This prevents a clean local and self-hosted user experience.

## Decision

Model authentication as a target-local strategy. Supported strategies should include Cloud device flow, generic OIDC, client credentials, token from stdin/env, and explicit no-auth development mode.

## Consequences

- Local stacks can use `client_credentials` with default development clients.
- Self-hosted stacks can use their own OIDC issuer.
- CI can use tokens or client credentials without browser flows.
- Cloud membership becomes one auth strategy, not the root abstraction.
18 changes: 18 additions & 0 deletions docs/adr/0003-api-version-resolution.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# ADR 0003: API Version Resolution Belongs In Runtime

Status: Accepted for v4 planning

## Context

The public SDK exposes versioned namespaces such as `Ledger.V1`, `Ledger.V2`, and `Payments.V3`. The stack exposes `/versions`, but not a full capabilities endpoint.

## Decision

Commands declare product features and available handlers. The runtime calls `/versions`, maps component versions to supported API namespaces, intersects that with command handlers, and selects the best compatible handler.

## Consequences

- Commands do not hardcode the oldest API namespace.
- New endpoints can appear as normal product commands and fail cleanly on older targets.
- A small manual compatibility table is still required for component version ranges.
- Most operation metadata can be generated from the OpenAPI spec.
18 changes: 18 additions & 0 deletions docs/adr/0004-cobra-thin-runtime.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# ADR 0004: Keep Cobra Thin

Status: Accepted for v4 planning

## Context

Cobra is widely used and already present in `fctl`, but current command implementations mix parsing, auth, client construction, API selection, and rendering.

## Decision

Keep Cobra for routing, flags, help, aliases, deprecations, and shell completions. Move target resolution, authentication, API versioning, and business logic into typed internal packages.

## Consequences

- Existing Cobra knowledge remains useful.
- Command files become smaller and easier to test.
- The runtime can be tested independently from Cobra.
- The CLI can keep a stable user experience while API versions evolve.
19 changes: 19 additions & 0 deletions docs/adr/0005-build-v4-in-isolated-directory.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# ADR 0005: Build v4 In An Isolated Directory

Status: Accepted for v4 planning

## Context

`fctl` v4 is intended to be a near-rewrite. The existing v3 code remains useful as a behavioral reference during implementation and review.

## Decision

Build the new CLI under a top-level `v4/` directory during the transition. Keep the existing root implementation intact until v4 has reached feature parity or an explicit cutover point.

## Consequences

- v3 remains available for comparison while v4 is built.
- Review is easier because new code is isolated from old code.
- The v4 module can start with a clean package layout.
- The final cutover will delete or archive the old root implementation and move the v4 implementation to the root.
- Build, release, and test commands must be explicit about whether they target v3 root or `v4/`.
21 changes: 21 additions & 0 deletions docs/cli-v4/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# fctl v4 Documentation

The v4 CLI is implemented under `v4/`, but its documentation lives here so it
can be reviewed with the repository-level architecture docs.

Read these in order when onboarding to v4:

1. `../rfcs/0001-fctl-v4-architecture.md` for the target architecture.
2. `../adr/` for accepted decisions.
3. `command-design.md` for command shape and Cobra boundaries.
4. `config-format.md` for profiles, contexts, and credential storage.
5. `runtime-behavior.md` for current login, scopes, stack waits, rendering, and
debug behavior.
6. `command-reference.md` for visible command families.
7. `migration-v3-v4.md` and `compatibility-aliases.md` for v3 compatibility.
8. `testing-strategy.md` for local and CI validation.
9. `implementation-audit.md` for current implementation status and known gaps.
10. `cutover-plan.md` for the future move out of `v4/`.

Keep `command-reference.md` and `runtime-behavior.md` aligned with Cobra help and
the manual command audit whenever commands are added, hidden, or renamed.
77 changes: 77 additions & 0 deletions docs/cli-v4/command-design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# fctl v4 Command Design

Commands should express Formance product intent, not OpenAPI or SDK structure.

Prefer:

```bash
fctl ledger transactions list
fctl ledger transactions revert <id>
fctl ledger schemas insert <version>
```

Avoid:

```bash
fctl ledger v2 transactions list
fctl ledger transactions list-v2
```

## Canonical Inputs

Each command should parse into a version-independent input model.

```go
type ListTransactionsInput struct {
Ledger string
AccountAddress string
PageSize int64
}
```

Version-specific adapters convert that model into generated SDK request types.

```go
func toLedgerV1(input ListTransactionsInput) operations.ListTransactionsRequest
func toLedgerV2(input ListTransactionsInput) operations.V2ListTransactionsRequest
```

## Renamed API Parameters

If API v1 calls a field `account` and API v2 calls it `address`, but the CLI concept is the same, expose one canonical flag.

```bash
fctl ledger transactions list --account users:123
```

Keep aliases only for CLI compatibility, not because generated API names changed.

## Version-Specific Features

A command can exist even if only newer targets support it.

```bash
fctl ledger transactions explain <id>
```

If the current target only supports an older Ledger API, return:

```text
ledger transactions explain requires Ledger >= 3.0.0.
Current target runs Ledger 2.3.4.
```

If the command requires an API operation that is not exposed by the public stack
spec or the current SDK, keep it hidden from the visible command surface until
the contract is explicit. `ledger transactions explain` currently follows this
rule.

## Help Text

Help should be stable and product-oriented. For flags or commands requiring newer APIs, include capability notes:

```text
--include-descendants Include child accounts (requires ledger API v2+)
```

Context-aware help can be added later, but the base help should remain useful without network calls.
Loading
Loading