Skip to content

docs: README overhaul#53

Merged
KalebCole merged 3 commits intomainfrom
pieter/readme-overhaul
Mar 30, 2026
Merged

docs: README overhaul#53
KalebCole merged 3 commits intomainfrom
pieter/readme-overhaul

Conversation

@KalebCole
Copy link
Copy Markdown
Owner

@KalebCole KalebCole commented Mar 30, 2026

Closes #47

Changes:

  • ghrb banner image at top
  • npm/license/node badges
  • 'Try it now' npx one-liner
  • Emoji feature grid (10 capabilities)
  • Numbered Quick Start (5 steps: auth → doctor → create → list → blast)
  • Command sections with real examples instead of tables
  • Global flags condensed to one line
  • Simplified auth setup
  • JSON envelope + exit codes section (compact)

References: gogcli, paperctl README styles

Before: 265 lines, table-heavy, install says npm install -g .
After: 200 lines, example-driven, install says npm i -g partiful-cli

Summary by CodeRabbit

  • Documentation
    • Revised installation guidance with multiple setup methods and a prominent "Try it now" command
    • Updated branding, banner and badges for improved presentation
    • Reorganized command reference into per-command sections; refreshed Quick Start to emphasize SMS login and running the health check before use
    • Simplified helper-command examples, removed NDJSON example blocks, and condensed global flags
    • Streamlined JSON output and exit-code docs; shortened contributing link

- Add ghrb banner image
- Add npm/license/node badges
- Add 'Try it now' npx one-liner
- Feature grid with emoji bullets
- Numbered Quick Start flow
- Command examples (not tables)
- Consolidated global flags to one line
- Simplified auth setup section
- Collapsed JSON envelope and exit codes

Closes #47
@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Mar 30, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5026ea77-2c7f-445e-bc7c-a2b2a972f851

📥 Commits

Reviewing files that changed from the base of the PR and between 17ab864 and 52bb3e3.

📒 Files selected for processing (1)
  • README.md
🚧 Files skipped from review as they are similar to previous changes (1)
  • README.md

📝 Walkthrough

Walkthrough

README rewritten: branding and header updated, banner and badges added, installation and quick start flows changed, command reference reorganized into per-command sections, examples refreshed, JSON/exit-code docs condensed, and contributing link text shortened.

Changes

Cohort / File(s) Summary
README Documentation
README.md
Full README overhaul: updated top header and banner, added badges, replaced installation instructions with npx/global install/clone+link workflows, reorganized command docs into per-command sections (including contacts, cohosts, posters, template, bulk, schema, doctor), revised Quick Start to emphasize partiful auth login +<phone> and partiful doctor, condensed JSON output and exit code docs, and shortened contributing link text.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

Poem

🐰 I hopped through README lines so bright,
Badges gleamed and headings light,
Commands in rows, a tidy song,
Quick start ready — hop along! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name Status Explanation Resolution
Linked Issues check ❓ Inconclusive The PR addresses most major objectives from #47 (hero section, badges, quick start, command reference), though terminal demos and agent integration sections were not implemented. Verify whether terminal demos (GIFs) and agent integration section were intentionally deferred or should be included in this PR.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'docs: README overhaul' directly and clearly summarizes the main change—a comprehensive rework of the README documentation.
Out of Scope Changes check ✅ Passed All changes are scoped to README.md documentation updates aligned with #47 objectives; no unrelated code modifications or extraneous changes detected.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch pieter/readme-overhaul

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 135db4168c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

README.md Outdated
#### `contacts` — Manage contacts
```bash
partiful cohosts list <eventId>
partiful cohosts add <eventId> --user <userId>
Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Replace unsupported --user flag in cohosts example

The documented command partiful cohosts add <eventId> --user <userId> does not match the CLI interface: registerCohostsCommands only defines --name and --user-id for cohosts add (see src/commands/cohosts.js). Users following this README example will hit an unknown/invalid option path and fail to add co-hosts.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

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

Fixed in 17ab864 and 52bb3e3 — all commands now verified against src/commands/*.js.

README.md Outdated
Comment on lines +124 to +125
partiful template save <eventId> --name "Weekly Game Night"
partiful template create <templateName>
Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Correct template command examples to existing subcommands

This section documents two invocations that the CLI does not support: template save has no <eventId> positional argument, and there is no template create subcommand (implemented subcommands are list/show/save/edit/delete in src/commands/templates.js). Copy-pasting these examples will produce command parsing errors instead of usable template workflows.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

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

Fixed in 17ab864 and 52bb3e3 — all commands now verified against src/commands/*.js.

README.md Outdated
Comment on lines +131 to +132
partiful bulk create --file events.json
partiful bulk update --file updates.json
Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Fix bulk examples that use non-existent --file options

Both bulk examples are incompatible with current command signatures: bulk create expects a positional <file> argument, while bulk update requires --filter plus update fields (see src/commands/bulk.js). The shown --file usage will fail at runtime, so users cannot run bulk operations as documented.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

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

Fixed in 17ab864 and 52bb3e3 — all commands now verified against src/commands/*.js.

Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

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

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@README.md`:
- Line 90: The README documents a non-existent subcommand "guests summary
<eventId>" but the command handler only provides "list" and "invite" in the
guests command implementation (see guests.js). Either remove or update the
README entry to reflect the actual subcommands ("list" and "invite"), or
implement the missing "summary" subcommand in the guests command handler (create
a "summary" branch/handler that accepts eventId and returns counts by status).
Update the README or code so both the documentation and the guests command
(list, invite, summary) are consistent.
- Around line 120-145: The README documents a non-existent CLI command group:
update either README.md to remove the `template` section (lines showing
`template list`, `template save <eventId> --name`, `template create
<templateName>`) or implement the missing CLI module `template.js` that
registers the `template` subcommands (`list`, `save`, `create`) with the same
flags and behavior; if implementing, ensure the module exports are wired into
the CLI command registry (where other commands like `bulk`, `schema`, `doctor`
are registered) and add corresponding help text and tests.
- Line 97: The README mentions a non-existent "blasts history" command (and
previously "list") while src/commands/blasts.js only registers the "send"
subcommand; either implement the missing subcommands or remove/update the docs.
Add and register a "history" subcommand handler in src/commands/blasts.js (e.g.,
implement a blastsHistoryHandler function and call
program.command(...).action(blastsHistoryHandler) or equivalent), and optionally
add a "list" subcommand handler if you want to restore that functionality;
ensure the handlers are exported/imported where needed and that command names
and help text match the README.
- Line 34: The README claims a `guests summary` command but the codebase only
implements `guests list` and `guests invite`; either remove the README
references or add the missing command. Fix option A: remove the "view summaries"
note and the documented `partiful guests summary <eventId>` usage from README.md
so docs match the implemented CLI (`guests list`, `guests invite`). Fix option
B: implement the command by adding a new CLI subcommand named `guests summary`
(register the command where other guest commands are registered), add a handler
(e.g., function getGuestSummaries or handleGuestsSummary) that accepts eventId,
retrieves/aggregates the summary data, and wire it into the existing CLI
help/usage output so `partiful guests summary <eventId>` works as documented.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ee183856-7674-4cd2-adec-fc46f097429b

📥 Commits

Reviewing files that changed from the base of the PR and between 46ad212 and 135db41.

📒 Files selected for processing (1)
  • README.md

- guests: summary → invite (matches guests.js)
- blasts: remove non-existent history subcommand
- cohosts: --user → --name (matches cohosts.js)
- template: fix subcommands to list/show/save/edit/delete
- bulk: create uses positional <file>, update uses --filter
Verified every command against src/commands/*.js and src/helpers/*.js:
- auth: save/refresh/clear → login/status/logout (SMS-based, not manual tokens)
- auth setup: removed DevTools token grabbing, replaced with auth login flow
- contacts: added [query] argument
- posters: added get <posterId>
- quick start: clarified eventId comes from step 4
@KalebCole KalebCole merged commit c1519fc into main Mar 30, 2026
1 check passed
@KalebCole KalebCole deleted the pieter/readme-overhaul branch March 30, 2026 00:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: README overhaul — hero, demos, feature grid, agent section

1 participant