Quail CLI

Quail CLI

quail-cli is a command-line interface for interacting with Quail, designed to simplify and automate operations such as user authentication, managing posts, and fetching user details.

Quail CLI interacts with the Quail API at https://api.quail.ink.

Install the latest release

macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/quailyquaily/quail-cli/master/scripts/install.sh | bash

Windows PowerShell:

irm https://raw.githubusercontent.com/quailyquaily/quail-cli/master/scripts/install.ps1 | iex

You can also check the latest release here, download the binary for your platform, extract it, and put it in your PATH.

Install manually

To manually install quail-cli, you can use the following command:

$ go install github.com/quailyquaily/quail-cli@latest

you need to have go installed to install quail-cli manually. Please refer to the official Go installation guide for more information.

Usage (command line)

After installation, you can start using quail-cli by calling the following command:

$ quail-cli [command]

Available Commands

• help: Get help about any command.
• init: Create a sample config file.
• login: Authenticate with Quail using OAuth or an API key.
• me: Retrieve current user information.
• post: Create, update, delete, or retrieve posts.
• reader: Read subscribed posts and comments.
• comments: Manage comments on your lists.

Global Flags

• --api-base string: Quail API base URL (default: https://api.quail.ink).
• --auth-base string: Quail Auth base URL (default: https://quaily.com).
• --config string: Path to the configuration file (default: $HOME/.config/quail-cli/config.yaml).
• --json: Output JSON instead of human-readable text.
• -h, --help: Display help information for the quail-cli.

Initialize Configuration

Create a sample config file:

$ quail-cli init

quail-cli init asks for an optional API key. Press Enter to leave it empty.

To pass the API key without a prompt:

$ quail-cli init --api-key QK-...

init does not overwrite an existing config file.

Authenticate with Quail

$ quail-cli login

This will initiate OAuth login to authenticate with Quail. Please follow the instructions to complete the authentication process.

1. Visit the URL provided in the terminal.
2. Authorize the application.
3. Copy the code shown in the browser.
4. Paste the code back into the terminal.

If a browser cannot be opened automatically, open the printed URL manually.

To use an API key instead of OAuth:

$ quail-cli login --api-key

You can also use QUAIL_API_KEY for scripts.

Retrieve Current User Information

$ quail-cli me

Get the details of the currently authenticated user.

Post Operations

Upsert a Post

$ quail-cli post upsert your_markdown_file.md -l your_list_slug

in which,

• your_markdown_file.md is the path to the markdown file.
• your_list_slug is the slug of the list where the post will be created or updated. For example, if the list URL is https://quaily.com/my_list, then your_list_slug is my_list.

quail-cli will read the frontmatter from the markdown file to create or update a post. If the post does not exist, it will be created. If it exists, it will be updated.

Here is an example of a markdown file:

---
title: "Here is the title"
slug: your-post-slug
datetime: 2024-09-30 18:42
summary: "This is a summary of the post."
tags: tag1, tag2, tag3
cover_image_url: "your-image-url.jpg"
---

> Any sufficiently advanced technology is indistinguishable from magic.
>
> -- Arthur C. Clarke

This is the body of the post.

    int main() {
        printf("Hello, World!");
        return 0;
    }

## Section Title

This is the last section of the post.

Publish/Unpublish/Deliver/Delete a Post

$ quail-cli post publish -l your_list_slug -p your_post_slug

$ quail-cli post unpublish -l your_list_slug -p your_post_slug

$ quail-cli post deliver -l your_list_slug -p your_post_slug

$ quail-cli post delete -l your_list_slug -p your_post_slug

Reader Operations

$ quail-cli reader subscriptions
$ quail-cli reader posts --limit 20 --offset 0
$ quail-cli reader read https://quaily.com/list-slug/post-slug
$ quail-cli reader comments --post 123
$ quail-cli reader comment --post 123 --content "Thanks for the post."

Comment Management

$ quail-cli comments latest --limit 50
$ quail-cli comments list --list your_list_slug --limit 20 --offset 0
$ quail-cli comments approve 123
$ quail-cli comments reject 123
$ quail-cli comments spam 123
$ quail-cli comments delete 123

Usage (MCP server)

Warning

This feature is experimental.

MCP(Model Context Protocol) is a protocol for interacting with AI models (like Claude, GPT, etc.). quail-cli can be used as a MCP server.

Before that, you need to login to quail-cli by running the following command:

$ quail-cli login

SSE mode

Run the following command to start the MCP server in SSE mode.

$ quail-cli mcp --sse

The server will start a HTTP server and listen on port 8083. You can use any MCP client to connect to this server by providing the URL http://localhost:8083/sse.

Stdio mode

Before configuring the quail-cli as a MCP server in stdio mode, you need to install quail-cli. And then, find the path of the quail-cli binary and pass mcp as the argument to the quail-cli.

/your_install_path/quail-cli mcp

Interact with quail-cli via MCP client

Here is an example prompt:

what's the url of the 1th post of my first channel?

The LLM will call a series of tools from quail-cli to get the answer.

Supported tools

• quaily_login: login to quaily.com.
• quaily_search: search quaily.com for a given query.
• quaily_get_my_channels: get all quaily channels of the current user.
• quaily_get_channel_posts: get posts of a specific quaily channel.
• quaily_get_post_content: get the content of a post.
• quaily_get_post: get a post.
• quaily_publish_post: publish a post.
• quaily_unpublish_post: unpublish a post.
• quaily_save_post: save a post.
• quaily_get_url: get the url of a post or a channel.

Configuration

By default, quail-cli reads from $HOME/.config/quail-cli/config.yaml. Create a sample file with quail-cli init, or let quail-cli login create it during the first login.

You can specify a different configuration file by using the --config flag.

$ quail-cli --config ./config.yaml init

Configuration File Example

# quail-cli stores API key and OAuth tokens in app.
app:
  api_key: ""
  access_token: ""
  expiry: ""
  refresh_token: ""
  token_type: ""
  user:
    id: 1
    name: "your_name"
    bio: "your_bio"

post:
  # Map your Markdown frontmatter keys to Quaily post fields.
  # In this example, "featureImage" in frontmatter maps to "cover_image_url".
  frontmatter_mapping:
    cover_image_url: featureImage

Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue.

License

This project is licensed under the GNU Affero General Public License v3.0.