Reference

Complete listing of every flag, configuration key, frontmatter field, and exit code.

Invocation

writer <slug> [options]
writer --setup

The <slug> is required for all commands except --setup and --help. It must be lowercase letters, digits, and hyphens only, with no leading or trailing hyphens.

Flags

Flag	What it does
`--draft`	Sets `draft: true` in frontmatter. Hugo omits draft posts from production builds.
`--no-push`	Builds the site but skips `git push`.
`--no-build`	Skips the build step; only runs `git commit` and `git push`.
`--toml`	Uses TOML frontmatter (`+++` delimiters) instead of YAML (`---`).
`--dry-run`	Prints the frontmatter that would be written and exits. No files are touched.
`--section <name>`	Puts the post in a different content section for this run (e.g. `notes`, `essays`).
`--ssg <name>`	Overrides the SSG for this run. Affects which defaults are applied.
`--setup`	Runs the interactive setup wizard. No slug required.
`-h`, `--help`	Prints the help message and exits.

Config keys

Set via writer --setup or by editing ~/.config/writer/config directly. Project-local .writerrc overrides the global config.

Key	Default	What it does
`SSG`	`hugo`	Which static site generator you use (`hugo`, `eleventy`, `jekyll`).
`BUILD_CMD`	`hugo --minify`	The exact shell command to build your site. Run after every confirmed post.
`CONTENT_DIR`	`content`	Directory that holds your posts, relative to the site root.
`DEFAULT_SECTION`	`posts`	Sub-directory inside `CONTENT_DIR` for new posts. Override per-run with `--section`.
`DEFAULT_TAGS`	(blank)	Comma-separated tags pre-filled at the tags prompt. Press Enter to accept, or type new tags to replace them.
`BUNDLE_FORMAT`	`true`	`true` → `slug/index.md` (page bundle). `false` → `slug.md` (flat file). Must be exactly `true` or `false`.
`FRONTMATTER_FORMAT`	`yaml`	`yaml` for `---` delimiters. `toml` for `+++` delimiters. Override per-run with `--toml`.
`EDITOR`	`micro`	Terminal editor binary. Any editor that accepts `editor +N file.md` works.
`GIT_COMMIT_MSG`	`new post: {slug}`	Commit message template. `{slug}` is replaced with the actual slug at runtime.
`TIMEZONE`	`auto`	`auto` uses the system timezone. Or set an IANA name: `America/Winnipeg`, `Europe/London`, `UTC`.
`SITE_DIR`	(blank)	Absolute path to your site root. Writer `cd`s here before anything else. Leave blank to use the current directory.

Config file format

Both ~/.config/writer/config and .writerrc use a simple INI-style format: KEY=value, one per line. Comments start with # and can be inline. Blank lines are ignored.

# ~/.config/writer/config

SSG=hugo
BUILD_CMD=hugo --minify
CONTENT_DIR=content
DEFAULT_SECTION=posts
BUNDLE_FORMAT=true        # true = slug/index.md, false = slug.md
FRONTMATTER_FORMAT=yaml   # yaml or toml
EDITOR=micro
GIT_COMMIT_MSG=new post: {slug}
TIMEZONE=auto             # auto = system TZ; or e.g. America/Winnipeg
SITE_DIR=                 # blank = use current directory

Frontmatter output

YAML (default)

---
title: "On the Meaning of Home"
date: 2026-05-23T14:32:00-06:00
slug: "on-the-meaning-of-home"
tags:
  - place
  - memory
description: "A meditation on what it means to belong somewhere."
draft: false
---

TOML (`--toml` or `FRONTMATTER_FORMAT=toml`)

+++
title = "On the Meaning of Home"
date = 2026-05-23T14:32:00-06:00
slug = "on-the-meaning-of-home"
tags = ["place", "memory"]
description = "A meditation on what it means to belong somewhere."
draft = false
+++"

Fields with no value provided are omitted from the output entirely, not written as empty strings. The description field is only added after you close the editor, once you've had a chance to write it.

Slug validation rules

Lowercase letters (a–z), digits (0–9), and hyphens (-) only
Must not start or end with a hyphen
No uppercase, underscores, dots, spaces, or other characters
Minimum one character

If the slug is invalid, writer prints a specific error explaining what's wrong and suggests a corrected version.

Exit codes

Code	Meaning
`0`	Success
`1`	Invalid slug, missing argument, missing dependency, or empty title
`2`	File already exists and you chose not to overwrite it
`3`	Build command failed (`BUILD_CMD` exited non-zero)
`4`	Git step failed (`git add`, `git commit`, or `git push`)
`5`	Config file has an unknown key or invalid value

Config loading order

Hardcoded defaults (in lib/defaults.sh)
Global config: ~/.config/writer/config
Writer cds to SITE_DIR if set
Project-local config: .writerrc in the current directory
CLI flags: highest priority, override everything

Dependencies

Tool	Required for	How to get it
`bash`	Running the script	Already on every Mac and Linux. Bash 3.2+ supported (macOS default).
`git`	Commit and push	`sudo apt install git` / already on macOS
`micro` (or other editor)	Opening the post for writing	micro-editor.github.io: `curl https://getmic.ro \| bash`
Hugo (or other SSG)	Building the site	gohugo.io/installation
`date`	Post timestamps	GNU date preferred; BSD date (macOS) also supported

Source & spec → ← Guide