Skip to content

Latest commit

 

History

History
279 lines (195 loc) · 11 KB

cli.org

File metadata and controls

279 lines (195 loc) · 11 KB

The command line, in pictures

What this is

A tour of the orgs command line: one picture per command worth seeing, and the line that draws it. Every command talks to a running orgs serve (or runs one in-process for itself with -local), so they all see the same notes, and anything changed in one shows up in the others and in worg.

The pictures are of a small demo notebook kept in docs/screenshots/demo; tools/screenshots takes them again (see Taking the pictures again).

Every command also takes -json, -format, -dry-run and -no-color, so what is drawn here for a person can be read by a program instead.

The day at a glance: orgs dash

One screen that answers “what does today want from me”: the agenda, the clock, the focus timer, the habits, the inbox and your watches, read together. It only reads; each card names the command that acts on it. orgs dash -w keeps it on screen, redrawn as things change, and orgs dash -json gives every card as data.

images/cli-dash.png

A card whose part of the server is missing or broken says so in one dim line, and the others still draw.

The morning standup: orgs standup

What you did since the last working day (Friday, on a Monday), what is on today and what is in the way, written in Slack’s markup so it can be pasted straight into a channel. -copy puts it on the clipboard as well, -md writes GitHub Markdown instead, -since mon starts from a day of your choosing and -n caps each section (the rest are counted).

images/cli-standup.png

Every part is read by the view it comes from (the agenda, the clock table, the weekly review’s waiting list, the dependency check), so a standup never says something the agenda would contradict.

The week in review: orgs recap

A week or a month on one page: what was finished, where the time went, how the habits held up, words written and what is still blocked. Like orgs standup it is Slack’s markup unless you ask for -md.

orgs recap                        # the last seven days
orgs recap -last -week            # last week, Monday to Sunday
orgs recap -month                 # this month so far
orgs recap -from 2026-10-01 -to 2026-10-15
orgs recap -block 2026-Q3 -md     # a clock table range, as Markdown

images/cli-recap.png

The agenda: orgs agenda

Three months of calendar, today’s entries, and the week underneath. , and . step a day, n comes back to today, t changes the keyword of the entry under the cursor, m opens the month.

images/cli-agenda.png

Planning the day: orgs plan

The day as hours: what is booked, what is free, and the tasks waiting for a slot, most urgent first. It is the agenda’s day planner in worg, at a prompt.

images/cli-plan.png

One screen for everything: orgs tui

A query’s results in a list, with the heading’s body beside it. : changes the query, / filters what is there, t changes a keyword, enter opens the heading in your editor.

images/cli-tui.png

Asking questions: orgs search

The same query language worg’s Search tab uses. Plain words match headlines; an expression can ask anything the database knows.

orgs search 'IsTask() && HasTags("work")'
orgs search 'DeadlineWithin("7d")' -json | jq '.[].Headline'

images/cli-search.png

Boards: orgs kanban

worg’s kanban boards, the same boards, editable from the terminal. H and L move a card between columns (which changes its keyword), J and K reorder it, t picks a keyword, c clocks in.

images/cli-kanban.png

Schedules: orgs gantt

A saved query drawn as a gantt chart, the same plan worg draws: EFFORT sizes a bar, AFTER and ORDERED chain them, weekends are skipped, and -crit marks the critical path.

images/cli-gantt.png

Column view: orgs cols

org’s column view of a file, from its #+COLUMNS: line. Parents total the columns that ask for it (%EFFORT{:}), enter edits a value in place, s sorts within each parent.

images/cli-cols.png

Habits: orgs habits

Every habit’s last month at a glance: █ kept, ░ missed, · not due. orgs habits done <name> ticks one off.

images/cli-habits.png

Tables: orgs tables

Every org table in your notes, in a picker with the table drawn beside it. ctrl-e runs its #+TBLFM formulas.

images/cli-tables.png

The weekly review: orgs review

Everything that wants a decision: projects with nothing to do next, deadlines nobody scheduled, things waiting on somebody else, time booked against open tasks. orgs review -fix walks them one at a time.

images/cli-review.png

Flashcards: orgs drill

Spaced repetition over your notes, org-drill style: the same cards, the same algorithms, the same DRILL_* properties. See Flashcards for how to write cards.

images/cli-drill.png

Checklists: orgs list

Every heading with - [ ] boxes in its own text is a list, wherever it lives, so a list refiled out of the inbox is still found, and so are the boxes under a task. orgs list picks one and works on it; orgs list ls draws them all, the way taskbook draws its boards.

orgs list                          # pick a list, then tick, add, edit, delete
orgs list new Packing for Oslo     # a new list, filed under Checklists in the inbox
orgs list ls -open                 # only lists with something left to do
orgs list check -l groceries 3 4   # tick items 3 and 4

images/cli-list.png

Agenda views: orgs agenda -view

Org’s custom agenda commands: a view is sections shown one after another (a day or a week of the agenda, open tasks with some keywords, a match, a search, stuck projects). Org’s own a, t, n and # are built in; more come from agenda: views: in the yaml or from worg, where each person keeps their own. orgs agenda -views lists them, and -as html or -as ics prints one for a page or a calendar.

images/cli-agenda-view.png

The hooks (orgs hooks), the phone’s calendar (orgs dav) and the language server (orgs lsp) have their pictures in their own guides.

Where the time went: orgs clocktable

Org’s clock table: the CLOCK: lines in every :LOGBOOK: over a range, added up by file and by heading. orgs clockin and orgs clockout write them; orgs clocks says what is running.

images/cli-clocktable.png

Source blocks: orgs code

Every #+BEGIN_SRC block in your notes, found by name, language or file, and run the way C-c C-c runs it, :var arguments and all.

orgs code ls -lang python    # the python blocks
orgs code run busiest        # run the block named busiest
orgs code run -w busiest     # and write #+RESULTS: under it

images/cli-code-run.png

What is in there: orgs stats

images/cli-stats.png

Finding your way: orgs help

Everything the command line can do is described by the binary itself, so the help always matches the version you are running. It needs no server.

You typeYou get
orgs helpevery command, grouped by what it is for, in the order worth reading
orgs help standupone command: what it does, its flags, examples and what the guides say
orgs help standno such command, so the names it might have meant (standup)
orgs help -allevery command with every flag, one after another, for searching
orgs help -jsonthe command list as a table (name, group, usage), for a script
orgs help -man searcha command’s man page (roff); with no command, orgs(1)
orgs help -man-dir DIRorgs.1 and an orgs-<command>.1 for every command, written into DIR
orgs completion zshtab completion for your shell

A command’s page reads top to bottom like this:

images/cli-help.png

Some ways to use it:

# Which command has a flag for this?
orgs help -all | grep -B20 -- '-since' | grep '^orgs '

# Read a long page in a pager (search has the whole query language)
orgs help search | less -R

# Real man pages: write them once, then `man orgs-search`
orgs help -man-dir ~/.local/share/man/man1

# The list for a launcher or a wrapper script
orgs help -json | jq -r '.[] | "\(.Name)\t\(.Usage)"'

Commands you add yourself show up too: every filter in your yaml is a command, listed under its own group (or “Other”). orgs p is the same list as a fuzzy picker, together with your saved queries and aliases.

Taking the pictures again

The pictures are taken by a script, against a demo server with its own notes, so they can be taken again whenever a command changes:

cd tools/screenshots
npm install
node capture.mjs                  # every picture
node capture.mjs cli-kanban       # just the ones named
node capture.mjs serve            # just the demo server, to look around

The demo notes are in docs/screenshots/demo. Their dates are written as {{D+3}} and filled in when the script runs, so the agenda is always about today. Terminal pictures run each command in a pseudo terminal and draw the screen with xterm.js; worg pictures drive Chrome with puppeteer.

An annotated picture (cli-dash) is a terminal picture with numbered badges and a legend. Its notes find their parts by text on the screen (a card’s top edge, or a line), so the badges follow the layout, and a renamed card fails the shot instead of putting a badge in the wrong place. These shots are taken last, because they set the demo up first (a pomodoro, a ticked habit, a watch that fires) and the other pictures shouldn’t show that.

The stories’ pictures live in tools/screenshots/stories/, one module a story. Each brings its own notebook (docs/screenshots/<story>/) and runs on a server of its own after the pictures above, so nothing one story sets up shows in another. node capture.mjs -story writer takes just one story’s. The whatsnew story is the pictures of the features added in v0.6.0 and v0.7.0 (checklists, agenda views, hooks, CalDAV, transclusion, the timer, org-protocol and citations), on the demo notes with docs/screenshots/whatsnew laid over them. The features story pictures org’s own features (clocking, source blocks, the editor, links, refiling, plots, collections) over docs/screenshots/features.