CLI

The Colonnes CLI is built into the desktop app. You do not need Bun, Node.js, or source code access to use it.

What you can do

  • Open a .col file
  • Open a file and jump directly to a calendar day, a space, or an item
  • Prepare a calendar day from its recurring rule
  • Print a calendar day, a space, or an item

Important notes

  • Open and ordinary print commands report their result in the app. Preparation and printing with --wait return JSON to the terminal.
  • Printing through CLI currently supports receipt_printer mode only.
  • Ordinary printing may ask before switching files. Preparation and print --wait refuse another active document without a dialog.
  • To print a specific item, you need its item ID.

Find an item ID

In the app:

  1. Right-click the item.
  2. Open Infos item.
  3. Copy the item ID.

Platform examples

macOS

"/Applications/Colonnes.app/Contents/MacOS/Colonnes" "/Users/you/Documents/todos.col"
"/Applications/Colonnes.app/Contents/MacOS/Colonnes" open "/Users/you/Documents/todos.col" --item YOUR_ITEM_ID
"/Applications/Colonnes.app/Contents/MacOS/Colonnes" print item --file "/Users/you/Documents/todos.col" YOUR_ITEM_ID

Windows

"C:\Program Files\Colonnes\Colonnes.exe" "C:\Users\You\Documents\todos.col"
"C:\Program Files\Colonnes\Colonnes.exe" open "C:\Users\You\Documents\todos.col" --item YOUR_ITEM_ID
"C:\Program Files\Colonnes\Colonnes.exe" print item --file "C:\Users\You\Documents\todos.col" YOUR_ITEM_ID

Linux

colonnes "/home/you/Documents/todos.col"
colonnes open "/home/you/Documents/todos.col" --item YOUR_ITEM_ID
colonnes print item --file "/home/you/Documents/todos.col" YOUR_ITEM_ID

If colonnes is not in your PATH, replace it with the full path to the app executable.

Common commands

Open a file:

colonnes "/path/to/file.col"

Open a file on today in calendar view:

colonnes open "/path/to/file.col" --calendar -d 0

Open a file on a specific day:

colonnes open "/path/to/file.col" --calendar --date 2026-06-12

Open a file on a space:

colonnes open "/path/to/file.col" --space root

Open a file on an item:

colonnes open "/path/to/file.col" --item YOUR_ITEM_ID

Print today from the calendar:

colonnes print calendar --file "/path/to/file.col" -d 0

Print a space:

colonnes print space --file "/path/to/file.col" root

Print an item:

colonnes print item --file "/path/to/file.col" YOUR_ITEM_ID

Optional print overrides

Use a specific print option:

colonnes print item --file "/path/to/file.col" --option selection_tickets_recursive YOUR_ITEM_ID

Supported print options:

  • task_tickets
  • task_tickets_recursive
  • selection_tickets
  • selection_tickets_recursive

Troubleshooting

If nothing seems to happen:

  • Check that the app window opened or came to the front.
  • Check the toast message in the app.
  • Make sure the file path is correct.
  • Make sure the item ID or space ID exists.
  • Make sure receipt printer mode is configured in the app before using print.

Prepare a calendar day

Configure recurrence rules in the document, then run:

colonnes prepare-calendar --file "/path/to/file.col" -d 0
colonnes prepare-calendar --file "/path/to/file.col" --date 2026-09-30

Exactly one date selector is required: --date YYYY-MM-DD or -d N. Today and future dates are allowed. A relative date is resolved once against the application’s local day.

The app starts if needed. If the same normalized file path is already open, the command uses its live store, including unsaved edits. Another active document produces an error without a confirmation dialog. Requests wait until the app is ready and execute sequentially.

A successful response arrives only after an atomic save:

{
  "requestId": "a-request-uuid",
  "file": "/path/to/file.col",
  "date": "2026-09-30",
  "status": "prepared",
  "createdCount": 24
}
Status Exit code Meaning
prepared 0 Copies and prepared marker saved
already_prepared 0 Day already prepared; current changes durably saved, no extra copies
no_matching_rule 2 No enabled rule matches; no copies or marker created
error 1 Invalid input, source, document conflict, save error, or timeout

Errors also include a message. After 120 seconds without a result, the command returns an error. Do not chain printing after an error or an unknown outcome. Retry preparation to check the saved state. If saving failed, the in-memory batch remains available for Retry save.

Wait for printing

colonnes print calendar --file "/path/to/file.col" --date 2026-09-30 --wait

--wait also works for item and space printing. It returns JSON with status: "printed" and exit code 0 after the print operation completes, or status: "error" and exit code 1. A printer accepting a job is not a physical-paper delivery guarantee. CLI printing supports receipt_printer mode only; configure the printer in the app first. No interactive file switch is allowed with --wait.

Printing always uses real items. It never prepares recurring tasks.

Prepare, then print the same day

Download prepare-and-print.py and run it with Python 3:

python3 prepare-and-print.py --executable "/Applications/Colonnes.app/Contents/MacOS/Colonnes" --file "/path/to/file.col" -d 0

The script parses preparation’s JSON, silently skips printing when there is no matching rule, and stops on errors. It prints the returned file and exact civil date with --wait, even if midnight passes between commands.

Preparation is idempotent; printing is not. Rerunning the whole script after already_prepared can reprint the receipt. Check the printer and previous result before retrying a failed or timed-out print.

Windows automation

Use the full executable path, quote paths with spaces, and run in the signed-in user’s desktop session. Python’s subprocess handling in the supplied script waits for the GUI executable and captures its JSON:

py prepare-and-print.py --executable "C:\Program Files\Colonnes\Colonnes.exe" --file "C:\Users\You\Documents\todos.col" -d 0

For direct PowerShell automation, use Start-Process -Wait -PassThru with -RedirectStandardOutput and inspect ExitCode; a GUI executable launched from an interactive shell can otherwise return control early. Windows Task Scheduler should run only while the user is logged on, with the configured printer accessible. Scheduled scripts must inspect exit codes and JSON before continuing.