Skip to content

Clarify --all flag behavior and document card statuses #54

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

Merged
robzolkos merged 2 commits into from
Jan 29, 2026
Merged

Clarify --all flag behavior and document card statuses #54

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
21d8a23
Clarify --all flag behavior and document card statuses
robzolkos Jan 29, 2026
29f2989
Update SKILL.md with card statuses documentation
robzolkos Jan 29, 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
41 changes: 39 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -203,6 +203,41 @@ fizzy card update 42 --created-at "2019-01-01T00:00:00Z"
fizzy card delete 42
```

### Card Statuses

Cards in Fizzy exist in different states. By default, `fizzy card list` returns **open cards only** (cards in triage or columns). To fetch cards in other states, use the `--indexed-by` or `--column` flags:

| Status | How to fetch | Description |
|--------|--------------|-------------|
| Open (default) | `fizzy card list` | Cards in triage ("Maybe?") or any column |
| Closed/Done | `fizzy card list --indexed-by closed` | Completed cards |
| Not Now | `fizzy card list --indexed-by not_now` | Postponed cards |
| Golden | `fizzy card list --indexed-by golden` | Starred/important cards |
| Stalled | `fizzy card list --indexed-by stalled` | Cards with no recent activity |

You can also use pseudo-columns:

```bash
fizzy card list --column done --all # Same as --indexed-by closed
fizzy card list --column not-now --all # Same as --indexed-by not_now
fizzy card list --column maybe --all # Cards in triage (no column assigned)
```

**Fetching all cards on a board:**

To get all cards regardless of status (for example, to build a complete board view), you need to make separate queries and combine the results:

```bash
# Open cards (triage + columns)
fizzy card list --board BOARD_ID --all

# Closed/Done cards
fizzy card list --board BOARD_ID --indexed-by closed --all

# Optionally, Not Now cards
fizzy card list --board BOARD_ID --indexed-by not_now --all
```

### Card Actions

```bash
Expand Down Expand Up @@ -593,13 +628,15 @@ Errors return a non-zero exit code and structured error info:

## Pagination

List commands return paginated results. Use `--page` to fetch specific pages or `--all` to fetch everything:
List commands return paginated results. Use `--page` to fetch specific pages or `--all` to fetch all pages:

```bash
fizzy card list --page 2
fizzy card list --all
fizzy card list --all # Fetches all pages of the current filter
```

> **Note:** The `--all` flag controls pagination only - it fetches all pages of results for your current filter. It does not change which cards are included. See [Card Statuses](#card-statuses) for how to fetch closed or postponed cards.

## Development

### Building
Expand Down
39 changes: 39 additions & 0 deletions skills/fizzy/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -276,6 +276,8 @@ fizzy card list --page 1 | jq '.data[:5]'
fizzy card list --all
```

**IMPORTANT:** The `--all` flag controls pagination only - it fetches all pages of results for your current filter. It does NOT change which cards are included. By default, `card list` returns only open cards. See [Card Statuses](#card-statuses) for how to fetch closed or postponed cards.

Commands supporting `--all` and `--page`:
- `board list`
- `card list`
Expand All @@ -287,6 +289,43 @@ Commands supporting `--all` and `--page`:

---

## Card Statuses

Cards exist in different states. By default, `fizzy card list` returns **open cards only** (cards in triage or columns). To fetch cards in other states, use the `--indexed-by` or `--column` flags:

| Status | How to fetch | Description |
|--------|--------------|-------------|
| Open (default) | `fizzy card list` | Cards in triage ("Maybe?") or any column |
| Closed/Done | `fizzy card list --indexed-by closed` | Completed cards |
| Not Now | `fizzy card list --indexed-by not_now` | Postponed cards |
| Golden | `fizzy card list --indexed-by golden` | Starred/important cards |
| Stalled | `fizzy card list --indexed-by stalled` | Cards with no recent activity |

You can also use pseudo-columns:

```bash
fizzy card list --column done --all # Same as --indexed-by closed
fizzy card list --column not-now --all # Same as --indexed-by not_now
fizzy card list --column maybe --all # Cards in triage (no column assigned)
```

**Fetching all cards on a board:**

To get all cards regardless of status (for example, to build a complete board view), make separate queries:

```bash
# Open cards (triage + columns)
fizzy card list --board BOARD_ID --all

# Closed/Done cards
fizzy card list --board BOARD_ID --indexed-by closed --all

# Optionally, Not Now cards
fizzy card list --board BOARD_ID --indexed-by not_now --all
```

---

## Common jq Patterns

### Reducing Output
Expand Down