Atlas

A command-line tool for managing Markdown worldbuilding vaults, built with Obsidian in mind.

Atlas creates, moves, deletes, lists, and searches notes in a vault of plain Markdown files. It keeps note ids and [[wiki links]] consistent when you reorganize, so renaming a note never leaves broken links behind.

Features

• Create notes from templates, with frontmatter written for you
• Move or rename notes and automatically update every wiki link that points at them
• Safe deletes: notes go to a trash folder instead of being erased
• Tree view of your vault and title search
• Works on plain .md files, so your vault stays usable in Obsidian or any other editor

Requirements

• Python 3.11 or newer

Installation

Quick start

cd ~/Documents/MyWorld
atlas init
atlas create "Nations/Republic of Valora" --type Nation
atlas list

atlas init marks a folder as an Atlas vault by creating a .atlas directory inside it. Every other command needs that directory to exist.

Finding your vault

Atlas looks for a vault in this order:

1. The path given with -v / --vault
2. The current directory, then up to five parent directories, stopping at the first one that contains .atlas

So you can run commands from any subfolder of your vault without passing a path. Global options go before the command:

atlas --vault ~/Documents/MyWorld list
atlas --quiet create "Characters/Aria"

Option	Description
-v, --vault PATH	Path to the vault.
--quiet	Silence messages from Atlas.
--version	Show the Atlas version.

Commands

Note names are paths relative to the vault root. The .md extension is optional.

atlas init

Initializes the current directory (or --vault) as an Atlas vault. This creates .atlas/ directory.

atlas create NAME [NAME ...]

Creates one or more notes. Missing folders are created for you. Each new note gets an id in its frontmatter, generated from its path, and a heading with its title.

atlas create "Nations/Republic of Valora"
atlas create "Characters/Aria" "Characters/Bram" --type character
atlas create "Places/Old Harbor" --template location --open

Option	Description
--type TYPE	Sets type in the note's frontmatter, lowercased.
-t, --template NAME	Starts the note from a template in .atlas/templates.
--open	Opens the last created note in $EDITOR.

atlas list

Prints a tree of every Markdown file in the vault. Hidden files and folders are skipped unless you pass -a / --all.

atlas search QUERY

Prints the vault-relative path of every note whose title contains the query. The match is case-insensitive and only looks at titles, not folders or note contents. Use -a / --all to include hidden directories such as the trash.

atlas search valora

atlas move SOURCE [SOURCE ...] DESTINATION

Moves or renames notes.

• With one source, the destination is the new path of the note.
• With several sources, the destination must be an existing folder.

atlas move "Nations/Valora" "Nations/Republic of Valora"
atlas move "Characters/Aria" "Characters/Bram" Archive

When a note moves, Atlas:

• Rewrites the note's frontmatter id to match its new path
• Updates wiki links in every note in the vault, including aliases ([[Note|alias]]), headings ([[Note#Heading]]), and embeds (![[Note]])
• Leaves links inside code blocks and inline code untouched
• Leaves a bare-title link alone when several notes share that title, since it is unclear which one was meant

All moves are checked before anything changes, so a bad argument never leaves the vault half moved. Pass --no-links to skip the link updates.

atlas delete NAME [NAME ...]

Moves notes to the vault's .trash folder instead of erasing them. A timestamp is added to the file name, so deleting a note with the same name twice never overwrites the earlier copy.

Templates

Templates are Markdown files in .atlas/templates. Pass the name without the .md suffix:

atlas create "Places/Old Harbor" --template location

Templates can have frontmatter and a body, and {{placeholders}} are filled in when the note is created:

Placeholder	Value
{{title}}	The note title (its file name without .md).
{{id}}	The generated note id.
{{date}}	Today's date as YYYY-MM-DD.

Unknown placeholders are left as they are. Example .atlas/templates/location.md:

---
type: location
created: "{{date}}"
tags: []
---

# {{title}}

## Description

## Notable people

The note id is always generated by Atlas, and a --type given on the command line overrides a type set in the template.

Vault layout

MyWorld/
├── .atlas/
│   ├── config.toml
│   └── templates/
├── .trash/
├── Nations/
│   └── Republic of Valora.md
└── Characters/
    └── Aria.md

License

MIT