Skill

A zero-dependency, stdlib-only Python CLI that lets AI agents read and write Corkboard wikis through the HTTP API. No MCP client, no SDK, no pip install — just Python 3 and a shell.

What Is the Skill

The Corkboard skill is a CLI bridge between your AI agent and your Corkboard workspace. It talks to your workspace through the Corkboard HTTP API and the MCP server, so your agent can create pages, edit content, upload media, search, and garden a workspace — all through standard shell commands. The skill is a single entrypoint script: python3 script/corkboard.py <command>.

For the full REST API reference, see the API docs.

Source: github.com/boldblackai/corkboard-skill

Install

Clone the skill into your agent's skills directory. Pick the one-liner for your agent:

Hermes

git clone https://github.com/boldblackai/corkboard-skill.git ~/.hermes/skills/corkboard

Claude Code

git clone https://github.com/boldblackai/corkboard-skill.git ~/.claude/skills/corkboard

Codex (OpenAI)

git clone https://github.com/boldblackai/corkboard-skill.git ~/.codex/skills/corkboard

Curl (single-file, any agent)

mkdir -p ~/agent-skills/corkboard/script
curl -sSL https://raw.githubusercontent.com/boldblackai/corkboard-skill/main/SKILL.md -o ~/agent-skills/corkboard/SKILL.md
curl -sSL https://raw.githubusercontent.com/boldblackai/corkboard-skill/main/script/corkboard.py -o ~/agent-skills/corkboard/script/corkboard.py
curl -sSL https://raw.githubusercontent.com/boldblackai/corkboard-skill/main/script/cb_client.py -o ~/agent-skills/corkboard/script/cb_client.py
curl -sSL https://raw.githubusercontent.com/boldblackai/corkboard-skill/main/script/cb_pages.py -o ~/agent-skills/corkboard/script/cb_pages.py
curl -sSL https://raw.githubusercontent.com/boldblackai/corkboard-skill/main/script/cb_collections.py -o ~/agent-skills/corkboard/script/cb_collections.py
curl -sSL https://raw.githubusercontent.com/boldblackai/corkboard-skill/main/script/cb_media.py -o ~/agent-skills/corkboard/script/cb_media.py

The skill uses a plain-directory layout: SKILL.md at the root, script/ for Python modules. No virtualenv, no post-install step.

Configuration

Set the API token in your agent's shell profile:

export CORKBOARD_TOKEN="cb_your_api_token"

CORKBOARD_TOKEN is required — the CLI exits with a clear error if it is missing.

CORKBOARD_URL is optional and defaults to https://corkboard.wiki. Set it only for self-hosted or development instances.

Getting a token: open your Corkboard workspace, go to Settings → API tokens, and create a personal access token. The token is a cb_… string bound to your workspace. Never hardcode it in files.

Verify: python3 script/corkboard.py list should print your workspace's top-level pages.

Usage

Invoke every command through the entrypoint: python3 script/corkboard.py <command> [options]

Pages

Command	Arguments	Description
get	<page>	Fetch a page by id (JSON to stdout).
put	<page> [--file \| --text] [--sum]	Create or replace a page. Replacing a page that already exists needs its current revision number (from the last get), otherwise the write is refused so concurrent edits are never silently overwritten.
append	<page> [--file \| --text] [--sum]	Append text to the end of a page. Needs the page's current revision number.
delete	<page>	Delete a page. Needs the page's current revision number.
edit	<page> (--old OLD --new NEW …) [--sum]	Surgical edit with unique-match assertions. Needs the page's current revision number (fetch-mutate-put_cas flow).
insert	<page> (--under \| --after \| --before) [--file \| --text] [--sum]	Insert content at an anchor position. Needs the page's current revision number.
find	<page> <pattern> [-E] [-i]	Search a page body with optional extended regex and case-insensitive flags.
move	<src> <dst>	Move/rename a page. Backlinks are rewritten and history preserved.
links	<page>	List outgoing wiki-links from a page.
backlinks	<page>	List pages that link to this page.
revisions	<page>	List revision history for a page.
revision-show	<page> <rev>	Show a specific revision's content.

Collections & Search

Command	Arguments	Description
list	[--ns NS] [--depth N]	List pages in a namespace. `--depth 0` = full recursion.
search	<query> [--ns NS]	Full-text search across pages.
sitemap	[--ns NS] [--depth N]	Render an ASCII tree of the page hierarchy.
wanted	(none)	List pages referenced by internal links but not yet created.
orphans	(none)	List pages with no inbound links.
semantic	<query>	Semantic (vector) search. Exits gracefully on Free plans.

Media

Command	Arguments	Description
media-upload	<file> <ns> <name>	Upload a file. Tries raw binary PUT first; falls back to base64 JSON. Replacing an existing file needs its current revision number; new files need none.
media-get	<id> [-o PATH]	Download a media file to path or stdout.
media-list	[--ns NS]	List media files, optionally filtered by namespace.
media-delete	<id>	Delete a media file. Needs the file's current revision number.
media-move	<src> <dst>	Move/rename a media file. Needs the file's current revision number.
media-orphans	(none)	List media files not referenced by any page.
media-usage	<id>	Show which pages reference a media file.

Common Flags

Flag	Applies to	Meaning
--sum MSG	put, append, edit, insert	Edit summary recorded in the page revision.
--file PATH / -F	put, append, insert	Read body from a file (exclusive with `--text`).
--text TEXT / -T	put, append, insert	Inline body text (exclusive with `--file`).

When neither --file nor --text is given, the body is read from stdin.

Examples

Creating and editing pages

# Create a page from stdin
echo "# Hello" | python3 script/corkboard.py put my/new-page --sum "first save"

# Append a section
echo "More content here." | python3 script/corkboard.py append my/new-page --sum "add section"

# Surgical edit — replace text with unique-match assertion
python3 script/corkboard.py edit my/new-page \
  --old "old heading" --new "new heading" \
  --sum "rename section"

Searching and navigating

# List top-level pages
python3 script/corkboard.py list

# Full-text search
python3 script/corkboard.py search "deployment"

# Semantic (vector) search
python3 script/corkboard.py semantic "how to configure CI"

# View the page hierarchy as an ASCII tree
python3 script/corkboard.py sitemap

# Find orphaned pages
python3 script/corkboard.py orphans

Uploading and managing media

# Upload an image
python3 script/corkboard.py media-upload screenshot.png screenshots hero

# List media in a namespace
python3 script/corkboard.py media-list --ns screenshots

# Download a media file
python3 script/corkboard.py media-get media_abc123 -o ./hero.png

# Find unreferenced media
python3 script/corkboard.py media-orphans

← Back to Docs