Skip to content

docs: remove cli audit-list #154

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
davidfrigolet wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

docs: remove cli audit-list #154

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
49 changes: 1 addition & 48 deletions docs/cli/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Command-line tool to execute Flamingock operations outside your application's no

## Overview

The Flamingock CLI spawns your application JAR in a separate JVM process, runs the requested operation, and returns structured results. This means you can run changes in CI/CD pipelines, audit history, diagnose issues, and fix audit states — before, after, or outside your application lifecycle.
The Flamingock CLI spawns your application JAR in a separate JVM process, runs the requested operation, and returns structured results. This means you can run changes in CI/CD pipelines, diagnose issues, and fix audit states — before, after, or outside your application lifecycle.

## Installation

Expand Down Expand Up @@ -115,33 +115,6 @@ flamingock execute apply --jar ./my-app.jar -J -Xmx512m -J -Xms256m
flamingock execute apply --jar ./my-app.jar -J -Xmx1g -- --spring.profiles.active=staging
```

### `audit list`

List audit entries from the change history.

| Option | Short | Required | Description |
|--------------|-------|----------|-----------------------------------------------------------------------------|
| `--jar` | `-j` | Yes | Path to the application JAR |
| `--history` | | No | Show full chronological history instead of snapshot |
| `--since` | | No | Filter entries since date (ISO-8601: `yyyy-MM-dd` or `yyyy-MM-ddTHH:mm:ss`) |
| `--extended` | `-e` | No | Show extended information (execution ID, class, method, hostname) |
| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) |
| `--` | | No | Separator — everything after is passed as application arguments |

```bash
# Current state (latest per change unit)
flamingock audit list --jar ./my-app.jar

# Full chronological history
flamingock audit list --jar ./my-app.jar --history

# Filter entries since a specific date
flamingock audit list --jar ./my-app.jar --since 2025-01-01

# Show extended information (execution ID, class, method, hostname)
flamingock audit list --jar ./my-app.jar --extended
```

### `audit fix`

Fix audit state for a change with issues. After manually verifying or fixing the state, mark the change as resolved.
Expand Down Expand Up @@ -222,25 +195,6 @@ flamingock issue get --jar ./my-app.jar -c user-change-v2 --json

## Example output

### Audit list output

```
Audit Entries Snapshot (Latest per Change Unit):
==================================================

┌──────────────────────────────┬────────┬──────────────────┬─────────────────────┐
│ Change ID │ State │ Author │ Time │
├──────────────────────────────┼────────┼──────────────────┼─────────────────────┤
│ create-users-collection │ ✓ │ platform-team │ 2025-01-07 10:15:23 │
│ add-user-indexes │ ✓ │ platform-team │ 2025-01-07 10:15:24 │
│ seed-initial-data │ ✗ │ data-team │ 2025-01-07 10:15:25 │
└──────────────────────────────┴────────┴──────────────────┴─────────────────────┘

Legend: ✓ = EXECUTED | ✗ = FAILED | ▶ = STARTED | ↩ = ROLLED_BACK

Total entries: 3
```

### Issue details output

```
Expand Down Expand Up @@ -338,4 +292,3 @@ If the CLI reports a missing entry point:
If `issue list` shows no issues but you expect some:
1. Verify you are connecting to the correct environment
2. Check if issues were already resolved
3. Use `audit list --history` to see all historical entries
37 changes: 5 additions & 32 deletions docs/resources/coming-from-mongock.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -350,49 +350,22 @@ After the first Flamingock run against a copy of your Mongock audit history, ver
Instead of inspecting the store manually, use the Flamingock CLI against your application JAR as the source of truth:

@bercianor bercianor Aug 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence now overstates what the CLI can validate. With audit list removed, issue list can only report inconsistent audit states, not validate imported audit history or confirm that changes were applied.

Could we narrow the wording accordingly, for example: “Use the CLI to identify inconsistent audit states”?


```bash
# Snapshot of the current audit state
flamingock audit list --jar ./my-app.jar

# Optional: full audit history
flamingock audit list --jar ./my-app.jar --history

# Optional: detect inconsistent states that require attention
# Detect inconsistent states that require attention
flamingock issue list --jar ./my-app.jar
```

Example snapshot output:

```text
Audit Entries Snapshot (Latest per Change Unit):
==================================================

┌──────────────────────────────┬────────┬──────────────────┬─────────────────────┐
│ Change ID │ State │ Author │ Time │
├──────────────────────────────┼────────┼──────────────────┼─────────────────────┤
│ create-users-collection │ ✓ │ platform-team │ 2025-01-07 10:15:23 │
│ add-user-indexes │ ✓ │ platform-team │ 2025-01-07 10:15:24 │
│ seed-initial-data │ ✓ │ data-team │ 2025-01-07 10:15:25 │
└──────────────────────────────┴────────┴──────────────────┴─────────────────────┘

Legend: ✓ = EXECUTED | ✗ = FAILED | ▶ = STARTED | ↩ = ROLLED_BACK

Total: 3 entries
```

Successful migration signal: legacy Mongock changes appear as executed, with no failed or in-progress states left behind.
Successful migration signal: `issue list` reports no issues — no failed or in-progress states left behind from the legacy Mongock changes.

Practical verification flow:

1. Run the application once with Flamingock enabled.
2. Run `flamingock audit list --jar ./my-app.jar`.
3. Confirm legacy Mongock changes that had already executed appear in the output and were not re-executed.
4. Confirm previously pending legacy changes now appear as executed.
5. Run `flamingock issue list --jar ./my-app.jar` and confirm no inconsistent audit states.
2. Run `flamingock issue list --jar ./my-app.jar` and confirm no inconsistent audit states.
3. Confirm previously pending legacy changes were applied (check application logs or the target system directly).

If your application needs profiles, datasource URLs, or other runtime arguments, pass them through the CLI as well:

```bash
flamingock audit list --jar ./my-app.jar -- --spring.profiles.active=staging
flamingock issue list --jar ./my-app.jar -- --spring.profiles.active=staging
```

## Production recommendations
Expand Down