archelon-0.7.1 is not a library.

archelon

This crate has been renamed to sapphire-journal. Please use sapphire-journal going forward.

Unified binary for archelon — a Markdown-based task and note manager. Provides both the CLI for humans and an MCP server for AI agents.

Installation

Install script (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/fluo10/archelon/main/install.sh | sh

Install script (Windows)

irm https://raw.githubusercontent.com/fluo10/archelon/main/install.ps1 | iex

From crates.io

cargo install archelon

From source

cargo install --path .

CLI usage

Initialize a journal

archelon init [PATH]

Creates .archelon/config.toml with the detected local timezone and .archelon/.gitignore.

Global options

# Override journal root (also settable via ARCHELON_JOURNAL_DIR env var)
archelon --journal-dir /path/to/journal <command>

Entry commands

Create a new entry

archelon entry new --title <TITLE> [--body "body text"] [OPTIONS]

Options:

--slug SLUG — override the filename slug
--tags tag1,tag2 — set tags
--task-due DATETIME — set task due date
--task-status STATUS — set task status (open | in_progress | done | cancelled | archived)
--event-start DATETIME, --event-end DATETIME

The filename is auto-generated as {year}/{caretta-id}_{slug}.md.

Create and edit in $EDITOR

archelon entry edit --new

Opens $EDITOR ($VISUAL → $EDITOR → vi) with a pre-filled frontmatter template. On save, the filename is adjusted to match the title.

List entries

archelon entry list [PATH] [OPTIONS]

Timestamp filters (OR'd across fields):

archelon entry list [PERIOD]      # positional PERIOD applies to all timestamp fields
--task-due PERIOD             # filter by task due date
--event-span PERIOD           # filter by event span overlap (in-progress events included)
--created-at PERIOD           # filter by created_at
--updated-at PERIOD           # filter by updated_at
--all-periods                 # match entries regardless of period

Task state filters:

--task-overdue                # tasks whose due date is past and not closed
--task-in-progress            # tasks currently in_progress
--task-unstarted              # tasks with status open and no started_at
--active                      # composite: overdue OR in-progress

Other filters (AND'd on top):

--task-status open,in_progress   # comma-separated status values
--tags work,urgent               # entry must have ALL specified tags

Sort:

--sort-by FIELD    # id | title | task_status | created_at | updated_at | task_due | event_start | event_end
--sort-order asc   # or desc (default: asc)

Output:

--json   # output all matching entries as JSON (metadata + body)

Display entries as a tree

archelon entry tree [PATH] [OPTIONS]

Displays entries in a parent-child hierarchy based on parent_id in frontmatter. Supports the same filter and sort options as entry list.

--json   # output the tree as JSON (nested children arrays)

Show an entry

archelon entry show <file-or-id>

Edit an entry

archelon entry edit <file-or-id>

Opens the entry in $EDITOR.

Update frontmatter fields

archelon entry modify <file-or-id> --title "New title"
archelon entry modify <file-or-id> --tags work,backend
archelon entry modify <file-or-id> --tags          # clear all tags
archelon entry modify <file-or-id> --task-status done

When --task-status is set to done, cancelled, or archived, closed_at is set automatically.

Check and fix filename

archelon entry check <file-or-id>   # report any filename/frontmatter mismatches
archelon entry fix <file-or-id>     # rename file to match frontmatter

Remove an entry

archelon entry remove <file-or-id>

Cache commands

archelon cache info       # show cache status and statistics
archelon cache sync       # incrementally update the cache
archelon cache rebuild    # drop and rebuild the cache from scratch

DATETIME format

YYYY-MM-DD or YYYY-MM-DDTHH:MM.

For deadline/end timestamps (--task-due, --event-end), date-only input is interpreted as 23:59. For start/close timestamps (--event-start, --task-closed-at), date-only input is interpreted as 00:00.

Journal configuration

.archelon/config.toml:

[journal]
timezone = "Asia/Tokyo"   # IANA timezone name
week_start = "monday"     # or "sunday" — used by this_week period

MCP server

archelon mcp launches an MCP (Model Context Protocol) server over stdio, letting AI agents (Claude, etc.) read and write journal entries.

Start the server

archelon mcp

Environment variables

Variable	Description
`ARCHELON_JOURNAL_DIR`	Path to the journal root. If not set, the server walks up from the current directory to find `.archelon/`.

Example: Claude Desktop

{
  "mcpServers": {
    "archelon": {
      "command": "archelon",
      "args": ["mcp"],
      "env": {
        "ARCHELON_JOURNAL_DIR": "/path/to/your/journal"
      }
    }
  }
}

Available tools

Tool	Description
`journal_init`	Initialize a new archelon journal
`entry_list`	List entries as JSON with filtering and sorting
`entry_tree`	List entries as a nested JSON tree (parent-child hierarchy)
`entry_show`	Show the contents of an entry by ID prefix or file path
`entry_new`	Create a new journal entry
`entry_modify`	Update frontmatter fields of an existing entry
`entry_check`	Validate an entry's frontmatter and filename
`entry_fix`	Rename an entry file to match its frontmatter
`entry_remove`	Delete an entry file
`cache_info`	Show cache status and statistics
`cache_sync`	Incrementally update the SQLite cache
`cache_rebuild`	Drop and rebuild the cache from scratch

`entry_list` parameters

Timestamp filters are OR'd across fields; task_status and tags are AND'd on top.

Parameter	Description
`period`	Shorthand: applies to all timestamp fields
`task_due`	Filter by task due date
`event_span`	Filter by event span overlap: matches entries whose event [start, end] overlaps the period
`created_at`	Filter by created_at
`updated_at`	Filter by updated_at
`task_overdue`	Include tasks whose due date is past and not closed
`task_in_progress`	Include tasks currently in_progress
`task_unstarted`	Include tasks with status open and no started_at
`active`	Composite: overdue OR in-progress
`task_status`	Array of statuses to include, e.g. `["open", "in_progress"]`
`tags`	Array of tags; entry must have ALL specified tags
`sort_by`	Field to sort by: `id` \| `title` \| `task_status` \| `created_at` \| `updated_at` \| `task_due` \| `event_start` \| `event_end`
`sort_order`	`"asc"` (default) or `"desc"`

License

MIT OR Apache-2.0

archelon 0.7.1