Command-line client¶

The cuhlumn command-line client calls the HTTP API. Writers, scripts, and AI agents use it to publish Markdown files and to manage sites and images. Every command prints JSON, so scripts and agents can read the result.

Installation¶

Build the client from a checkout of the repository:

cargo install --path crates/cli

The command installs the cuhlumn binary in ~/.cargo/bin.

Settings¶

cuhlumn health needs only the server address. cuhlumn site list needs the server address and the token. Every other site, post, media, and announce command also needs the site.

A new server without a token is in setup mode. The admin sets the token on the Setup page of the console, or sets CUHLUMN_TOKEN on the server. Until then, admin commands fail with the needs_setup error. The client uses the token that the admin set.

Commands¶

cuhlumn --help and cuhlumn <command> --help show every option.

Post files¶

A post file is Markdown with YAML front matter:

---
title: How we back up SQLite
description: Our nightly routine for one database file.
tags: [Databases, Ops]
status: published
---

We back up **one SQLite file** every night.

The client checks the file before it sends it. Unknown fields, a missing title, an empty body, or an invalid value stop the command with a message that names the field.

Replacement and drafts¶

post push replaces the complete entry. To edit an entry, start from the stored version:

cuhlumn post get sqlite-backups --markdown > sqlite-backups.md
# edit sqlite-backups.md
cuhlumn post push sqlite-backups.md

post get --markdown writes every field, so the file keeps the status and the publication time.

post push refuses to turn a published entry into a draft by accident. The file must say status: published, or you pass --publish to keep the entry public or --draft to hide it.

Field assignments¶

site set and post set read the stored object, change the named fields, and save the result.

The client checks the result before it sends it.

Appearance and IndexNow fields¶

cuhlumn site set indexnow:=false
cuhlumn site set brand.palette=sepia brand.home_layout=cards
cuhlumn site set brand.code_theme=ocean brand.card_style=light
cuhlumn site set 'brand.social:=[{"network": "github", "url": "https://github.com/maralind"}]'

The social networks are github, gitlab, codeberg, mastodon, bluesky, x, threads, linkedin, youtube, instagram, discord, telegram, and email. Each url is an absolute https:// address, at most 500 characters. For email, the url is a mailto: address with one recipient.

Announcement bar¶

cuhlumn announce shows, replaces, or removes the announcement bar of the site.

cuhlumn announce set "Maintenance on Sunday." --tone warning \
  --link https://harbor.example.com/maintenance --label Details \
  --from 2026-11-10T09:00:00Z --until 2026-11-15T18:00:00Z
cuhlumn announce show
cuhlumn announce clear

TIME is an RFC 3339 time, such as 2026-11-10T09:00:00Z, or unix seconds, such as 1794301200. announce set replaces the whole announcement. Omitted options take their defaults, also when the old announcement had other values.

Every announce command prints the status and the announcement:

{"status": "scheduled", "announcement": {"text": "Maintenance on Sunday.", "link": "https://harbor.example.com/maintenance", "link_label": "Details", "tone": "warning", "starts_at": 1794301200, "ends_at": 1794765600, "dismissible": true}}

Images¶

media upload sends the file with the type from its extension: .png, .jpg, .jpeg, .webp, .gif, or .avif.

{
  "name": "ba7816bf8f01cfea414140de5dae2223.png",
  "url": "https://blog.example.com/media/ba7816bf8f01cfea414140de5dae2223.png",
  "path": "/media/ba7816bf8f01cfea414140de5dae2223.png"
}

Use path in posts and settings, because it works on every domain and port.

Output and exit codes¶

Server errors start with the error code, for example error: conflict: .... Delete commands print nothing on success. post get --markdown, skill, and install-skill print text instead of JSON.

Agent skill¶

The file skills/cuhlumn/SKILL.md explains the client to AI agents. The binary contains the same file, so the installed skill always matches the installed client.

Install the skill¶

cuhlumn install-skill installs the skill with the skills installer, the same installer that other agent skills use.

cuhlumn install-skill                         # asks for the agents and the scope
cuhlumn install-skill -g -a claude-code -y    # Claude Code, for this user
cuhlumn install-skill -a '*' -y               # every agent, in this project

The command does these steps:

1. It writes the skill of the binary to <user cache>/cuhlumn/skill/skills/cuhlumn/SKILL.md.
2. It runs npx --yes skills@latest add <that folder>, or pnpm dlx skills@latest add <that folder> when npx is not installed.
3. The installer copies or links the skill into the skills folder of each agent that you select.

The user cache is %LOCALAPPDATA% on Windows, ~/Library/Caches on macOS, and $XDG_CACHE_HOME or ~/.cache on Linux. A project install records that folder in skills-lock.json. Run cuhlumn install-skill again after you upgrade the client.

Install the skill without Node.js¶

The installer needs Node.js with npx, or pnpm. Without them, save the skill in the skills folder of your agent:

mkdir -p ~/.agents/skills/cuhlumn
cuhlumn skill > ~/.agents/skills/cuhlumn/SKILL.md