pineal-cli

pineal, the Pineal terminal client. A third front-end alongside the web app and the Discord bot, scoped to quick capture and status — drop a task in two seconds without leaving the tool you're in. Moves, labels, assigns, and filters stay in the web app where the keyboard layer shines.

All reads and writes go through Convex HTTP actions under /cli/*. The CLI never imports the Convex client SDK.

Install

From npm (published by the Release CLI workflow on a cli-v* tag):

npm install -g pineal-cli

That puts pineal on your $PATH (the package is pineal-cli; the binary is pineal). Requires Node 18+.

From source (for local development):

pnpm install
pnpm --filter pineal-cli build
# the bin is at cli/dist/index.js. Link it onto your PATH:
cd cli && pnpm link --global

Log in

The CLI uses a device-code flow: it prints a short code and a URL, you approve in the browser, and a per-user token is issued back to the terminal.

pineal login --convex-url https://adept-ptarmigan-286.convex.site \
             --web-url    https://<your-pineal-host>

• --convex-url is the Convex deployment's site URL (the *.convex.site one, not *.convex.cloud). The CLI remembers it after the first run.
• --web-url is wherever your pineal-web container is served (the URL the approval link should point at). Defaults to http://localhost:5173.

You'll see something like:

To finish login, open:
  https://pineal.example/device?code=ABCD2345

Your code: ABCD-2345
(Expires in 15 minutes.)

Waiting…

Open the URL, confirm the code matches, and the terminal will print Logged in. on its own.

The token is saved to ~/.config/pineal/config.json (or $XDG_CONFIG_HOME/pineal/config.json) with mode 0600.

Pick a project

The CLI keeps an "active project" so most commands don't need a -p flag.

pineal use my-project-slug

Override per-command with -p <slug>.

Commands

pineal login      Authenticate with Pineal via device-code flow
pineal logout     Clear local credentials
pineal whoami     Show current user and active project
pineal use <slug> Set the active project for this shell

pineal new <title>     Create a task in the active project's Todo status
  -d, --description <text>      Task description (use '-' to read stdin)
  -p, --project <slug>          Override the active project
      --priority <level>        urgent | high | medium | low
                                (or !!!, !!, !, .)
  -m, --mine                    Assign the new task to you
      --done                    Create the task directly in the Done status

pineal log <title>     Record completed work: a task assigned to you, already
                       Done. Sugar for `pineal new <title> --mine --done`.
  -d, --description <text>      Task description (use '-' to read stdin)
  -p, --project <slug>          Override the active project
      --priority <level>        urgent | high | medium | low

pineal mine            List your open tasks (everything not Done)
  -p, --project <slug>

pineal doing           List the active project's In Progress column
  -p, --project <slug>

pineal show <id>       Show task detail
pineal done <id>       Move a task to the Done status

<id> is the full Convex task id (the one pineal new and pineal mine print on the left). Tab-complete from your shell history.

Examples

# Quick capture
pineal new "fix the build"
pineal new "rewrite the auth middleware" --priority !!!

# Long description from your editor or stdin
pineal new "draft launch post" -d "$(cat post.md)"
git log --oneline -1 | pineal new "blame ${USER} for this commit" -d -

# Inbox check
pineal mine
pineal doing
pineal show jh7d… # paste the id
pineal done jh7d…

Non-goals

By design, the CLI does not ship move, label, archive, edit, or filtering flags, nor general assign (assigning other people). Those are richer in the web client, and the v3 spec deliberately keeps the CLI to capture + status. The one exception is self-assignment on create (--mine), which exists so an agent can log its own completed work in one shot (pineal log). If you want to reorganize the board, open it in the browser.

Environment overrides

| Var | Purpose | | --- | --- | | PINEAL_TOKEN | Override the saved CLI token (handy for CI) | | PINEAL_CONVEX_SITE_URL | Override the Convex site URL | | PINEAL_WEB_BASE_URL | Override the web base URL used in printed links |

CONVEX_SITE_URL and WEB_BASE_URL (no PINEAL_ prefix) also work, to match the bot's env vars when you share a shell config.

Development

pnpm --filter pineal-cli dev      # tsx watch
pnpm --filter pineal-cli build    # tsc -b → dist/
pnpm --filter pineal-cli typecheck

Or from the repo root: pnpm dev:cli.

The HTTP routes live in convex/http.ts under /cli/*; the per-user auth resolution and task helpers are in convex/cli.ts. The /device approval page lives at web/src/pages/device.tsx.