quail-cli

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:

1. QUAIL_API_KEY
2. saved app.api_key
3. 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.