Metadata-Version: 2.4
Name: fizzydo
Version: 0.2.0
Summary: Command-line client for the fizzy.do kanban API
Project-URL: Homepage, https://github.com/delip/fizzy-cli
Project-URL: Repository, https://github.com/delip/fizzy-cli
Project-URL: Issues, https://github.com/delip/fizzy-cli/issues
Author: Delip Rao
License-Expression: MIT
License-File: LICENSE
Keywords: cli,fizzy,fizzy.do,kanban,productivity,task-management
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: markdown-it-py>=3.0
Requires-Dist: markdownify>=0.11
Requires-Dist: python-dotenv>=1.0
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: twine>=5.1; extra == 'dev'
Description-Content-Type: text/markdown

# fizzydo

Command-line client for the [fizzy.do](https://fizzy.do) kanban API.

`fizzydo` is a thin, ergonomic CLI over the fizzy.do REST API for boards, columns, cards, comments, steps, tags, and pins. Resource-first command shape: `fizzydo cards list`, `fizzydo boards create --name ...`, `fizzydo cards close 42`.

## Install

```sh
pip install fizzydo
```

Or with [pipx](https://pipx.pypa.io) / [uv](https://github.com/astral-sh/uv) for an isolated install:

```sh
pipx install fizzydo
# or
uv tool install fizzydo
```

For development against a local checkout:

```sh
pip install -e ".[dev]"
pytest
```

Requires Python 3.11+.

## Authentication

`fizzydo` authenticates with a personal access token from your fizzy.do profile (Profile → API → Personal access tokens → Generate new access token).

Set the token in `FIZZYDO_API_KEY`:

```sh
export FIZZYDO_API_KEY=your-token-here
```

If the env var is unset, `fizzydo` reads it from a `.env` file. Lookup order:

1. `--env-file-path <path>` (explicit override)
2. `./.env` (current directory)
3. `$HOME/.env`

A `.env` looks like:

```
FIZZYDO_API_KEY=your-token-here
FIZZYDO_ACCOUNT=897362094         # optional, account slug
FIZZYDO_BASE_URL=https://app.fizzy.do  # optional
```

## Quick start

```sh
fizzydo auth whoami                # list your accounts
fizzydo boards list                # see your boards
fizzydo cards list --mine          # cards assigned to you

# Create, comment on, and close a card
BOARD=$(fizzydo boards list --id | head -1)
fizzydo cards create --board "$BOARD" --title "Add dark mode" --description "We need dark mode."
fizzydo comments add 42 "Started looking into this."
fizzydo cards close 42

# Read a card with its description, checklist, and comments inline
fizzydo cards show 42

# Drop a card straight into a column instead of triage
DOING=$(fizzydo columns list --board "$BOARD" --id | sed -n '2p')
fizzydo cards create --board "$BOARD" --column "$DOING" \
  --title "Wire up dark mode toggle" --description @dark-mode.md

# Bulk-import a directory of markdown files as cards
fizzydo cards bulk-create --board "$BOARD" --column "$DOING" --from-dir ./tasks/
```

## Output modes

- Default: human-friendly Rich tables. `cards show <n>` is the exception — it
  renders the card's title, metadata, the description body (HTML→markdown via
  Rich), the checklist with `[x]`/`[ ]` markers, and every comment, all inline.
- `--json` — emit raw JSON for piping into `jq`. For `cards show`, this returns
  `{"card": {...}, "comments": [...]}` so you can fetch both in one round trip.
- `--id` — emit only IDs (or card numbers), one per line, for scripting:

```sh
fizzydo cards list --mine --id | xargs -n1 fizzydo cards close
```

`cards list --status all` is a true union: it issues two requests (open feed +
closed feed), dedupes by id, and re-sorts by `last_active_at`. Other status
values still hit the API once.

## Rich-text input

`--description` (cards) and the comment body argument accept several input forms:

- Inline plain text: `--description "Quick note"`
- A Markdown file: `--description @notes.md`
- An HTML file: `--description @body.html`
- Stdin (Markdown): `--description -`
- An editor: `comments add 42 --editor`

## Commands

| Resource | Subcommands |
|---|---|
| `auth` | `whoami`, `status` |
| `boards` | `list`, `show`, `create`, `update`, `delete`, `publish`, `unpublish` |
| `columns` | `list`, `show`, `create`, `update`, `delete` |
| `cards` | `list`, `show`, `create`, `bulk-create`, `update`, `delete`, `close`, `reopen`, `not-now`, `triage`, `untriage`, `tag`, `assign`, `golden`, `ungolden`, `watch`, `unwatch` |
| `comments` | `list`, `show`, `add`, `update`, `delete` |
| `steps` | `list`, `add`, `done`, `undo`, `update`, `delete` |
| `tags` | `list` |
| `pins` | `list`, `add`, `remove` |

Run `fizzydo <resource> --help` for full options on any subcommand.

A few ergonomics worth knowing:

- `cards create --column COL` triages the new card straight into a column,
  skipping the implicit triage step.
- `cards bulk-create --from-dir ./tasks/` walks `*.md` files and creates one
  card per file. The H1 (`# Title`) becomes the title; the rest is the
  description. Combine with `--column` and `--id` for agent-driven flows.
- `boards create --description ...` is an alias for `--public-description`.
- `steps done|undo|update|delete` accept either a literal step ID **or** a
  1-based index into the card's checklist (`fizzydo steps done 42 1`).

## Exit codes

| Code | Meaning |
|---|---|
| `0` | Success |
| `1` | Generic / network / config error |
| `2` | 401 Unauthorized |
| `3` | 403 Forbidden |
| `4` | 404 Not Found |
| `5` | 422 Unprocessable Entity (validation) |
| `6` | 429 Too Many Requests |
| `7` | 5xx Server Error |

## Using fizzydo from an agent

`fizzydo` is designed to be driven by coding agents (Claude Code, Codex CLI, etc.) for project task tracking. The recommended workflow — one board per project, three columns (`TODO`/`DOING`/`DONE`), cards moved through them as work progresses — is documented in [FIZZYDO_AGENT_USE.md](FIZZYDO_AGENT_USE.md). Point your agent at that file at the start of a session.

## Not yet implemented

Webhooks, notifications, reactions, users admin, account settings, file/image uploads, and ETag-based caching are deferred to follow-up iterations. The fizzy.do API spec lives in `Fizzy_API.md` if you want to track what's still missing.

## License

MIT — see `LICENSE`.
