CLI commands¶
The full command tree below is generated directly from Waymark's Typer application, so it always matches the installed version.
Run waymark with no arguments to launch the guided Textual interface; every
command here is also available directly for scripting, testing, and quick
capture.
waymark¶
Waymark: your private memory trail, searchable from the terminal.
Usage¶
waymark [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--version |
Show the installed Waymark version. | No | False |
--plain |
Show the plain non-interactive menu. | No | False |
--install-completion |
Install completion for the current shell. | No | - |
--show-completion |
Show completion for the current shell, to copy it or customize the installation. | No | - |
Commands¶
| Name | Description |
|---|---|
tui |
Launch the guided terminal interface. |
doctor |
Check local Waymark setup and runtime... |
capture |
Capture a manual memory in local SQLite... |
timeline |
Show recent memories in reverse... |
today |
Show today's captures, due reflections,... |
ask |
Search saved memories with keyword FTS or... |
reflect |
Generate an app-only reflection from saved... |
journey |
Inspect journey map signals and capture... |
decision |
Track decisions and review judgment over... |
setup |
Preview and save first-run setup... |
models |
Inspect local model runtime state without... |
import |
Import explicit user-selected files. |
sources |
Inspect imported source metadata. |
export |
Export memories and reflections to... |
reflections |
Inspect saved reflections. |
memory |
Inspect saved memories. |
embeddings |
Build explicit local embedding indexes. |
backup |
Create and restore full local backups of... |
Subcommands¶
tui¶
Launch the guided terminal interface.
Usage¶
waymark tui [OPTIONS]
Arguments¶
No arguments available
Options¶
No options available
doctor¶
Check local Waymark setup and runtime availability.
Usage¶
waymark doctor [OPTIONS]
Arguments¶
No arguments available
Options¶
No options available
capture¶
Capture a manual memory in local SQLite storage.
Usage¶
waymark capture [OPTIONS] [TEXT]
Arguments¶
| Name | Description | Required |
|---|---|---|
TEXT |
Memory text. If omitted, Waymark will prompt for it. | No |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-t, --type TEXT |
Memory type such as daily, project, work, health. | No | daily |
--tag TEXT |
Tag for this memory. Can be repeated. | No | - |
--local-ai, --ai |
Use the configured local Ollama chat model to draft memory fields. | No | False |
--preview, --dry-run |
Show the drafted memory card without saving it. | No | False |
-y, --yes |
Save a local-AI draft without an interactive confirmation prompt. | No | False |
timeline¶
Show recent memories in reverse chronological order.
Usage¶
waymark timeline [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-n, --limit INTEGER |
Number of memories to show. | No | 20 |
today¶
Show today's captures, due reflections, decisions, and next commands.
Usage¶
waymark today [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--date TEXT |
Date to inspect in YYYY-MM-DD format. | No | - |
--commands-only |
Print only the suggested next commands. | No | False |
ask¶
Search saved memories with keyword FTS or explicit local embeddings.
Usage¶
waymark ask [OPTIONS] QUERY
Arguments¶
| Name | Description | Required |
|---|---|---|
QUERY |
Keyword query for the current app-only search. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-n, --limit INTEGER |
Number of source memories. | No | 5 |
--semantic |
Use explicitly generated local embedding vectors. | No | False |
reflect¶
Generate an app-only reflection from saved memories.
Usage¶
waymark reflect [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-p, --period TEXT |
Reflection period: today, week, or month. | No | week |
--save |
Save the generated reflection locally. | No | False |
--force |
Save even if this reflection window already exists. | No | False |
journey¶
Inspect journey map signals and capture prompts.
Usage¶
waymark journey [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
No options available
Subcommands¶
prompts¶
Show copyable capture commands for thin memory areas.
Usage¶
waymark journey prompts [OPTIONS]
Arguments¶
No arguments available
Options¶
No options available
decision¶
Track decisions and review judgment over time.
Usage¶
waymark decision [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
No options available
Subcommands¶
add¶
Add an open decision.
Usage¶
waymark decision add [OPTIONS] TITLE
Arguments¶
| Name | Description | Required |
|---|---|---|
TITLE |
Decision title. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-c, --context TEXT |
Decision context. | Yes | - |
-o, --option TEXT |
Decision option. Can be repeated. | No | - |
--confidence INTEGER RANGE |
Confidence from 1 to 5. | No | - |
--review-date TEXT |
Optional review date, such as 2026-06-12. | No | - |
-m, --memory INTEGER |
Memory entry id to link. Can be repeated. | No | - |
list¶
List tracked decisions.
Usage¶
waymark decision list [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--status TEXT |
Filter by status, such as open or done. | No | - |
-n, --limit INTEGER |
Number of decisions. | No | 20 |
review¶
Show decisions due for review or waiting for outcomes.
Usage¶
waymark decision review [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-n, --limit INTEGER |
Number of decisions to inspect. | No | 100 |
show¶
Show a decision with linked memory context.
Usage¶
waymark decision show [OPTIONS] DECISION_ID
Arguments¶
| Name | Description | Required |
|---|---|---|
DECISION_ID |
Decision id. | Yes |
Options¶
No options available
link¶
Link a decision to a saved memory.
Usage¶
waymark decision link [OPTIONS] DECISION_ID ENTRY_ID
Arguments¶
| Name | Description | Required |
|---|---|---|
DECISION_ID |
Decision id. | Yes |
ENTRY_ID |
Memory entry id to link. | Yes |
Options¶
No options available
unlink¶
Remove a memory link from a decision.
Usage¶
waymark decision unlink [OPTIONS] DECISION_ID ENTRY_ID
Arguments¶
| Name | Description | Required |
|---|---|---|
DECISION_ID |
Decision id. | Yes |
ENTRY_ID |
Memory entry id to unlink. | Yes |
Options¶
No options available
finalize¶
Mark a decision as decided.
Usage¶
waymark decision finalize [OPTIONS] DECISION_ID
Arguments¶
| Name | Description | Required |
|---|---|---|
DECISION_ID |
Decision id. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-c, --choice TEXT |
Final choice. | Yes | - |
--confidence INTEGER RANGE |
Updated confidence from 1 to 5. | No | - |
outcome¶
Record an outcome after reviewing a past decision.
Usage¶
waymark decision outcome [OPTIONS] DECISION_ID
Arguments¶
| Name | Description | Required |
|---|---|---|
DECISION_ID |
Decision id. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-o, --outcome TEXT |
Observed outcome. | Yes | - |
setup¶
Preview and save first-run setup recommendations.
Usage¶
waymark setup [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--apply |
Write the recommended local config without downloading models. | No | False |
Subcommands¶
models¶
Inspect recommended local models and exact manual pull commands.
Usage¶
waymark setup models [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--apply |
Write the recommended local config while leaving model downloads manual. | No | False |
models¶
Inspect local model runtime state without downloads.
Usage¶
waymark models [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
No options available
Subcommands¶
list¶
List locally installed Ollama models without downloading anything.
Usage¶
waymark models list [OPTIONS]
Arguments¶
No arguments available
Options¶
No options available
check¶
Check configured local AI models against installed Ollama models.
Usage¶
waymark models check [OPTIONS]
Arguments¶
No arguments available
Options¶
No options available
import¶
Import explicit user-selected files.
Usage¶
waymark import [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
No options available
Subcommands¶
markdown¶
Import one explicit Markdown file as a memory entry.
Usage¶
waymark import markdown [OPTIONS] PATH
Arguments¶
| Name | Description | Required |
|---|---|---|
PATH |
Path to one Markdown file. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--force |
Import even if this exact file path was imported before. | No | False |
text¶
Import one explicit plain text file as a memory entry.
Usage¶
waymark import text [OPTIONS] PATH
Arguments¶
| Name | Description | Required |
|---|---|---|
PATH |
Path to one .txt or .text file. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--force |
Import even if this exact file path was imported before. | No | False |
pdf¶
Import one explicit PDF file as a memory entry.
Extracts only the existing text layer. Scanned or image-only PDFs are not
OCR'd. Requires the optional pypdf package.
Usage¶
waymark import pdf [OPTIONS] PATH
Arguments¶
| Name | Description | Required |
|---|---|---|
PATH |
Path to one .pdf file. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--preview, --dry-run |
Show extracted card without saving. | No | False |
--force |
Import even if this exact file path was imported before. | No | False |
docx¶
Import one explicit Word .docx file as a memory entry.
Extracts paragraph text only. Styles, images, and embedded objects are not imported.
Usage¶
waymark import docx [OPTIONS] PATH
Arguments¶
| Name | Description | Required |
|---|---|---|
PATH |
Path to one .docx file. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--preview, --dry-run |
Show extracted card without saving. | No | False |
--force |
Import even if this exact file path was imported before. | No | False |
markdown-folder¶
Legacy Markdown-only folder importer. Prefer waymark import folder.
Usage¶
waymark import markdown-folder [OPTIONS] PATH
Arguments¶
| Name | Description | Required |
|---|---|---|
PATH |
Path to a folder of Markdown files. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--apply |
Actually import the previewed files. | No | False |
--recursive |
Include nested folders. | No | False |
--limit INTEGER RANGE |
Maximum Markdown files to preview/import. | No | 25 |
--force |
Import files even if their paths were imported before. | No | False |
folder¶
Preview or import all supported files (.md, .txt, .pdf, .docx) from one folder.
Usage¶
waymark import folder [OPTIONS] PATH
Arguments¶
| Name | Description | Required |
|---|---|---|
PATH |
Path to a folder of supported files. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--apply |
Actually import the previewed files. | No | False |
--recursive |
Include nested folders. | No | False |
--limit INTEGER RANGE |
Maximum files to preview/import. | No | 25 |
--force |
Import files even if their paths were imported before. | No | False |
sources¶
Inspect imported source metadata.
Usage¶
waymark sources [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
No options available
Subcommands¶
list¶
List imported sources.
Usage¶
waymark sources list [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-n, --limit INTEGER |
Number of sources. | No | 20 |
export¶
Export memories and reflections to explicit Markdown files.
Usage¶
waymark export [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
No options available
Subcommands¶
memory¶
Export one saved memory to Markdown.
Usage¶
waymark export memory [OPTIONS] ENTRY_ID OUTPUT
Arguments¶
| Name | Description | Required |
|---|---|---|
ENTRY_ID |
Memory entry id to export. | Yes |
OUTPUT |
Markdown file to write. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--force |
Overwrite the output file if it already exists. | No | False |
timeline¶
Export recent memories to one Markdown timeline.
Usage¶
waymark export timeline [OPTIONS] OUTPUT
Arguments¶
| Name | Description | Required |
|---|---|---|
OUTPUT |
Markdown file to write. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-n, --limit INTEGER |
Number of memories. | No | 20 |
--force |
Overwrite the output file if it already exists. | No | False |
reflection¶
Export one saved reflection to Markdown.
Usage¶
waymark export reflection [OPTIONS] REFLECTION_ID OUTPUT
Arguments¶
| Name | Description | Required |
|---|---|---|
REFLECTION_ID |
Saved reflection id to export. | Yes |
OUTPUT |
Markdown file to write. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--force |
Overwrite the output file if it already exists. | No | False |
reflection-trends¶
Export saved reflection trend summaries to Markdown.
Usage¶
waymark export reflection-trends [OPTIONS] OUTPUT
Arguments¶
| Name | Description | Required |
|---|---|---|
OUTPUT |
Markdown file to write. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-p, --period TEXT |
Optional period: today, week, or month. | No | - |
--tag TEXT |
Only include saved windows containing this tag. | No | - |
-t, --type TEXT |
Only include saved windows containing this memory type. | No | - |
--force |
Overwrite the output file if it already exists. | No | False |
reflections¶
Inspect saved reflections.
Usage¶
waymark reflections [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
No options available
Subcommands¶
list¶
List saved reflections.
Usage¶
waymark reflections list [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-n, --limit INTEGER |
Number of reflections. | No | 20 |
due¶
Show reflection windows with memories but no saved reflection.
Usage¶
waymark reflections due [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--generate-next |
Generate the first due reflection without saving. | No | False |
--save-next |
Generate and save the first due reflection. | No | False |
compare¶
Compare a current generated reflection with the latest saved period.
Usage¶
waymark reflections compare [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-p, --period TEXT |
Reflection period: today, week, or month. | No | week |
trends¶
Summarize trends across saved reflections.
Usage¶
waymark reflections trends [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-p, --period TEXT |
Optional period: today, week, or month. | No | - |
--tag TEXT |
Only include saved windows containing this tag. | No | - |
-t, --type TEXT |
Only include saved windows containing this memory type. | No | - |
show¶
Show one saved reflection.
Usage¶
waymark reflections show [OPTIONS] REFLECTION_ID
Arguments¶
| Name | Description | Required |
|---|---|---|
REFLECTION_ID |
Saved reflection id. | Yes |
Options¶
No options available
memory¶
Inspect saved memories.
Usage¶
waymark memory [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
No options available
Subcommands¶
show¶
Show one memory card with source and linked decisions.
Usage¶
waymark memory show [OPTIONS] ENTRY_ID
Arguments¶
| Name | Description | Required |
|---|---|---|
ENTRY_ID |
Memory entry id. | Yes |
Options¶
No options available
edit¶
Edit selected fields on a saved memory.
Usage¶
waymark memory edit [OPTIONS] ENTRY_ID
Arguments¶
| Name | Description | Required |
|---|---|---|
ENTRY_ID |
Memory entry id. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--text TEXT |
Replace the raw memory text. | No | - |
--title TEXT |
Replace the memory title. | No | - |
--summary TEXT |
Replace the memory summary. | No | - |
-t, --type TEXT |
Replace the memory type. | No | - |
--tag TEXT |
Replace tags. Can be repeated. | No | - |
--clear-tags |
Remove all tags from this memory. | No | False |
embeddings¶
Build explicit local embedding indexes.
Usage¶
waymark embeddings [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
No options available
Subcommands¶
status¶
Show explicit local embedding index readiness.
Usage¶
waymark embeddings status [OPTIONS]
Arguments¶
No arguments available
Options¶
No options available
backfill¶
Preview or explicitly generate missing entry embeddings.
Usage¶
waymark embeddings backfill [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--apply |
Generate embeddings for the previewed entries. | No | False |
--limit INTEGER RANGE |
Maximum entries to preview or embed. | No | 10 |
backup¶
Create and restore full local backups of your Waymark home.
Usage¶
waymark backup [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
No options available
Subcommands¶
create¶
Write a full JSON backup of your Waymark home to one explicit file.
Usage¶
waymark backup create [OPTIONS] PATH
Arguments¶
| Name | Description | Required |
|---|---|---|
PATH |
Output .json backup file path. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--force |
Overwrite an existing backup file. | No | False |
info¶
Show what a backup file contains without restoring it.
Usage¶
waymark backup info [OPTIONS] PATH
Arguments¶
| Name | Description | Required |
|---|---|---|
PATH |
Backup .json file to inspect. | Yes |
Options¶
No options available
restore¶
Rebuild your Waymark home from a backup file.
Refuses to overwrite a home that already holds memories unless --force is passed, in which case existing data is cleared first.
Usage¶
waymark backup restore [OPTIONS] PATH
Arguments¶
| Name | Description | Required |
|---|---|---|
PATH |
Backup .json file to restore from. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--force |
Overwrite the current home if it already has memories. | No | False |
bundle¶
Write a restore-ready backup plus readable Markdown exports to one folder.
Usage¶
waymark backup bundle [OPTIONS] PATH
Arguments¶
| Name | Description | Required |
|---|---|---|
PATH |
Output folder for the portable bundle. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--force |
Write into an existing non-empty bundle folder. | No | False |