| name | quail-cli |
| description | Help users operate Quaily from the command line with quail-cli. Use when the user wants to log in with OAuth or API key, configure quail-cli, read subscriptions and posts, read or write comments, manage author comments, publish or manage posts, or output JSON for scripts. |
Quail CLI
What To Do
Help the user use quail-cli to work with Quaily. Give commands they can run, explain required flags, and keep defaults simple.
Default output is human-readable. Use --json only when the user asks for JSON, scripting, piping, or jq.
Never ask the user to paste an API key or token into chat. Tell them to use quail-cli init --api-key, quail-cli login --api-key, or QUAIL_API_KEY in their shell.
Install
For macOS and Linux, install the latest release with:
curl -fsSL https://raw.githubusercontent.com/quailyquaily/quail-cli/master/scripts/install.sh | bash
For Windows PowerShell, install the latest release with:
irm https://raw.githubusercontent.com/quailyquaily/quail-cli/master/scripts/install.ps1 | iex
If the user does not want to run a remote install script, point them to the official GitHub releases page:
https://github.com/quailyquaily/quail-cli/releases
Tell them to download the binary for their operating system, extract it, and put the quail-cli binary in PATH.
If the user has Go installed, they can install from source:
go install github.com/quailyquaily/quail-cli@latest
Verify installation:
quail-cli version
If quail-cli is not found, the binary is not in PATH. Explain how to fix PATH for the user's shell only when they ask for OS-specific help.
Configuration
Create a sample config file:
quail-cli init
init asks for an optional API key. Press Enter to leave it empty.
To create the file and save an API key without a prompt:
quail-cli init --api-key QK-...
To use a non-default config path:
quail-cli --config ./config.yaml init
init does not overwrite an existing config file.
Authentication
For normal interactive use:
quail-cli login
quail-cli prints the OAuth URL. After authorization, tell the user to copy the code shown in the browser and paste it back into the terminal.
If a browser is not available on the machine running quail-cli, tell the user to open the printed URL on another machine where they are logged in.
For API key login:
quail-cli login --api-key
For scripts and temporary sessions:
QUAIL_API_KEY=QK-... quail-cli me
Auth priority is:
QUAIL_API_KEY- saved
app.api_key
- saved OAuth token
Global Options
Use these options before or after the command:
quail-cli --json me
quail-cli --api-base https://api.quail.ink me
quail-cli --auth-base https://quaily.com login
quail-cli --config ./config.yaml me
Do not use --format; --json is the supported JSON switch.
Reader Tasks
List subscriptions:
quail-cli reader subscriptions
List posts from subscribed lists:
quail-cli reader posts --limit 20 --offset 0
Read a post by Quaily URL:
quail-cli reader read https://quaily.com/list-slug/post-slug
Read a post by list and post id or slug:
quail-cli reader read --list list-slug --post post-slug
Read comments for a post:
quail-cli reader comments --post 123
Write a comment:
quail-cli reader comment --post 123 --content "Thanks for the post."
reader read <URL> supports standard https://quaily.com/{list_slug}/{post_slug} URLs. Do not assume custom domains are supported.
Author Tasks
List latest comments across the user's lists:
quail-cli comments latest --limit 50
List comments for one list:
quail-cli comments list --list list-slug --limit 20 --offset 0
Moderate comments:
quail-cli comments approve 123
quail-cli comments reject 123
quail-cli comments spam 123
quail-cli comments delete 123
Use list id or list slug when a command accepts --list.
Post Tasks
Create or update a post from Markdown frontmatter:
quail-cli post upsert post.md --list list-slug
Publish while upserting:
quail-cli post upsert post.md --list list-slug --publish
Operate on an existing post:
quail-cli post publish --list list-slug --post post-slug
quail-cli post unpublish --list list-slug --post post-slug
quail-cli post deliver --list list-slug --post post-slug
quail-cli post delete --list list-slug --post post-slug
JSON Output
Use --json for automation:
quail-cli --json reader subscriptions
quail-cli --json reader read https://quaily.com/list-slug/post-slug
quail-cli --json comments latest --limit 10
When explaining JSON usage, prefer commands that can be piped into jq.
Troubleshooting
For unauthorized user, check login state first:
quail-cli me
If using an API key, confirm the shell variable is present without printing the key:
test -n "$QUAIL_API_KEY"
For scripts, prefer QUAIL_API_KEY over writing a config file.
If a command needs access to private or paid content, the authenticated user must have permission to read it.
