YKanBan/USAGE.md

YKanBan Usage

YKanBan is a local, offline kanban board. Like Git, it keeps its data in a .ykanban folder inside the project folder it manages (the workspace). Each YKanBan window manages exactly one workspace; several windows can run at the same time on different workspaces.

Installing

Each release build is self-contained; no .NET runtime is needed.

Platform	Package	Executable
Windows x64	YKanBan-<version>-win-x64-setup.exe	YKanBan.exe
Linux x64	YKanBan-<version>-linux-x64.tar.gz	YKanBan
macOS Apple silicon	YKanBan-<version>-osx-arm64.dmg	YKanBan.app (see macOS)

Only Apple silicon macOS is a release target; there is no Intel Mac build.

On Windows, run the installer. On Linux, extract the archive anywhere. On macOS, open the disk image and drag YKanBan.app into Applications (or any other folder). To type ykanban <path> as shown below, put the executable on your PATH under that name, for example:

# Linux
ln -s /opt/YKanBan-<version>-linux-x64/YKanBan ~/.local/bin/ykanban
# macOS
ln -s /Applications/YKanBan.app/Contents/MacOS/YKanBan /usr/local/bin/ykanban

On Windows, add the installed folder to PATH (the default is C:\Program Files\YKanBan); ykanban then finds YKanBan.exe because Windows ignores case.

Starting YKanBan

The only way to start YKanBan is with the workspace path:

ykanban <path>

• Exactly one argument is accepted. A relative path is resolved against the current working directory, so ykanban . opens the current folder (but see macOS when starting through open).
• YKanBan looks for .ykanban only in <path> itself; it does not search parent folders the way Git does.
• There are no command-line options. An argument starting with - is never treated as a path; to open a folder whose name starts with -, write it as ./-name.

The path must exist and be a folder. When the board cannot be shown, the whole window shows one of these pages instead:

Page	When
Invalid arguments	No argument, more than one argument, an empty or whitespace-only argument, an argument starting with - (including --help), a path the operating system cannot represent (for example one containing a NUL character), or a path that does not exist or is not a folder. Shows the usage line.
No workspace here	<path> exists but has no .ykanban. The Initialize workspace button creates one, with the columns To Do / In Progress / Done and the preset tags (both named in the current interface language).
Workspace locked	Another YKanBan window already has this workspace open. Close that window first. Also shown when another window takes the lock while you initialize.
Cannot open workspace	.ykanban exists but ykanban.db in it is missing (restore it from a backup, or delete .ykanban and initialize again; YKanBan never silently creates an empty board), the database was created by a newer YKanBan, is damaged or cannot be opened, or a file-system or permission error occurred (also when initializing fails for a reason other than the lock). The English error details can be selected and copied.

The window title is <workspace name> - YKanBan while a workspace is open and just YKanBan on these pages.

macOS

The app is not notarized. After dragging it out of the disk image, remove the download quarantine once, or macOS refuses to open it:

xattr -dr com.apple.quarantine YKanBan.app

Double-clicking YKanBan.app starts it without a path, so it only shows the Invalid arguments page. Start it from a terminal instead, either through Launch Services or by running the executable inside the bundle:

open -n -a YKanBan --args /path/to/project
/Applications/YKanBan.app/Contents/MacOS/YKanBan /path/to/project

• Keep -n: without it, open only brings an already running YKanBan to the front and drops the path, instead of starting another window.
• Give open an absolute path. An app started by open runs in /, so open -n -a YKanBan --args . opens /, not the current folder. Running the executable inside the bundle resolves relative paths normally.
• open -a YKanBan finds the app once it is in /Applications (or another folder Launch Services knows about).

Workspaces, Git and Backups

• Do not commit .ykanban to Git. Add it to your global ignore file once, so no repository picks it up. If git config --global core.excludesFile prints a file, add the line .ykanban/ to that file; otherwise create one:

  echo ".ykanban/" >> ~/.gitignore_global
  git config --global core.excludesFile ~/.gitignore_global
  

• Back up or move all three database files together: ykanban.db, ykanban.db-wal and ykanban.db-shm in .ykanban/. Recent changes may still be in the -wal file; copying only ykanban.db can lose them. The simplest safe backup is to close YKanBan and copy the whole .ykanban folder.

• Network shares (SMB, NFS, …) are not supported. The database and the workspace lock rely on local file-system features that do not work reliably over a network. YKanBan does not detect this; keep workspaces on a local disk.

• .ykanban/ykanban.lock is held while a window has the workspace open and is released automatically when YKanBan exits or crashes. The file itself is kept empty; only the exclusive OS handle it carries has meaning.

Search Syntax

Type an expression in the search box on the Board tab and click Search (or press Enter). Searching only happens then; there is no search while typing. The × button clears the box and shows every card again.

• Columns are always shown, even when none of their cards match.
• An empty or blank expression shows every card.
• An active search keeps the result set it produced until you search again: after adding, editing, moving or deleting cards the board shows the same matching cards as before, minus any that were deleted. Adding or editing a card does not change whether it is currently shown; press Search again to refresh the result.

Examples

Expression	Finds cards…
login	whose title or content contains "login"
login crash	containing both words (anywhere in title or content)
login OR signup	containing either word
tag:bug title:login	tagged bug whose title contains "login"
tag:bug OR tag:ui	tagged bug or ui
(tag:bug OR tag:ui) column:Done	tagged bug or ui in the column titled "Done"
"dark mode"	whose title or content contains "dark mode"
tag:"needs review"	tagged needs review
id:61 or id:#61	number 61
"http://example.com"	containing the URL (a : must be quoted)
"AND"	containing the text "AND"

Grammar

query     := orExpr
orExpr    := andExpr ( OR andExpr )*
andExpr   := operand ( (AND)? operand )*      -- neighbours are joined by AND
operand   := atom | '(' orExpr ')'
atom      := word | phrase | qualifier
qualifier := key ':' value
key       := tag | title | content | id | column
value     := word | phrase                    -- tag / title / content / column
           | '#'? digit+                       -- id: a positive decimal integer
word      := one or more characters, except whitespace and ( ) " : \ ;
             not equal to AND or OR
phrase    := '"' one or more characters '"'   -- escapes: \" and \\

Operators

• AND and OR are operators only in uppercase. and and or are ordinary words.
• Writing words next to each other means AND: a b is a AND b.
• AND binds tighter than OR: a OR b c is a OR (b AND c). Use parentheses to group differently: (a OR b) c.
• To search for the literal text AND or OR, quote it: "AND", tag:"OR".
• The search keywords (AND, OR, tag, title, content, id, column) are always English, whatever the interface language. Qualifier keys are lowercase only: Tag:bug is an unknown qualifier.

What Each Atom Matches

Atom	Matches when
word or phrase	the card title or content contains the text
title: value	the card title contains the text
content: value	the card content contains the text
tag: value	the card has a tag whose name equals the text
column: value	the card is in a column whose title equals the text
id: value	the card number equals the value

• A qualifier value can be a word (tag:bug) or a phrase (tag:"needs review"). Use a phrase for values containing spaces, (, ), : or \, and for the values AND / OR.
• id: takes an unquoted positive integer, optionally prefixed with #: id:61, id:#61.

Quoting and Escapes

• A phrase is text in double quotes. Inside it, \" stands for a quote and \\ for a backslash; any other backslash is an error.
• Outside quotes, \ is not allowed at all, and : always starts a qualifier. Quote any text containing them: "C:\\temp", "a:b".
• A phrase cannot be empty, and must be separated from neighbouring words and phrases by a space or a parenthesis: write a "b", not a"b".
• A qualifier's phrase value follows the : directly: tag:"needs review", not tag: "needs review".

Case

All matching ignores case, for letters of every language: tag:BUG finds bug, and ÄRGER finds ärger. Text is otherwise compared literally: %, _ and * have no special meaning.

Tag names and column titles must each be unique, but the uniqueness check is case-sensitive: Bug and bug are different names and can both exist. Because matching folds case, a query such as tag:bug then matches both.

Invalid Expressions

An invalid expression does not search. A dialog shows "The query expression is invalid. Details: …" followed by the parser's message (always in English). After closing it, the box keeps your text for correcting and the board keeps the previous result.

These are invalid:

Problem	Example
Unbalanced parentheses	(tag:bug, tag:bug)
An operator with a missing side	bug AND, OR bug
Consecutive operators	a AND OR b
A qualifier without a value	tag:
AND / OR as an unquoted qualifier value	tag:AND (write tag:"AND")
An unterminated phrase	"dark mode
An empty phrase	"", tag:""
A phrase touching other text	a"b", "a"b, "a""b"
A space between a qualifier and its phrase value	tag: "needs review"
An invalid escape in a phrase	tag:"a\x"
A backslash outside a phrase	C:\temp
An unknown qualifier key	label:bug, Tag:bug, http://x
An unquoted value containing :	title:a:b
An id: value that is not an unquoted positive integer	id:abc, id:0, id:"61"

Settings File

Settings (language, theme, card sort order, column width and the confirmation switches) are stored in app.json:

Platform	Location
Windows	%APPDATA%\YKanBan\app.json
Linux, macOS	~/.config/YKanBan/app.json ($XDG_CONFIG_HOME/YKanBan/app.json when that is set)

• The file is written when YKanBan exits. With several instances running, the last one to exit overwrites the file with its own settings.
• A language change takes effect after restarting YKanBan; a theme change applies as soon as the settings dialog is accepted.
• A missing file is normal on first run and yields the defaults. If the file exists but cannot be read (an I/O or permission error), the defaults are used.
• If the file cannot be parsed, it is saved as app.json.bak and the defaults are used. This also covers an invalid enum value: an unknown theme, sort or width string, or a numeric enum value, makes the whole file fall back to defaults. A section that is simply missing falls back to its own defaults.