Complete CLI & Configuration Reference

This page provides the comprehensive specification for all SenaVN command-line options, subcommands, flags, and persistent configuration keys.


Command Line Interface (CLI)

Syntax Overview

sena [SUBCOMMAND] [OPTIONS]

Running sena with no arguments launches the interactive Brick TUI browser.


Commands Specification

sena add

Add a new visual novel to the local SQLite database.

sena add <NAME_OR_QUERY> <ID> [PATH] [OPTIONS]
Argument / Flag Description
NAME_OR_QUERY VNDB search query string or game title
ID Unique alphanumeric identifier for local database
PATH Optional executable path. If omitted and --skip is absent, triggers the interactive file picker
--vndb-id <ID> Direct VNDB ID (e.g. v2002)
--developer <DEV> Override developer name
--release-date <YYYYMMDD> Override release date integer
--rating <SCORE> Override rating score (0.0 - 10.0)
--description <TEXT> Override description
--tag <TAG> Add custom tag (repeatable)
--no-fetch Skip VNDB query; create local-only record
-s, --skip Non-interactive mode: skip confirmation and file picker
-o, --order <N> Auto-select Nth search result
--keep-name Retain supplied NAME instead of VNDB title

sena use

Associate executable, save folder, and guide file paths with a game.

sena use <ID> [PATH] [--save [PATH]] [--guide [PATH]]
Argument / Flag Description
ID Game identifier
[PATH] Executable path. Omit to launch interactive file picker
--save [PATH] Save folder path. Omit [PATH] to launch interactive directory picker
--guide [PATH] Walkthrough file path. Omit [PATH] to launch interactive file picker

sena run

Launch game process and start background tracking daemon.

sena run [ID_OR_NAME] [OPTIONS]
Flag Description
ID_OR_NAME Game ID or title query
-s, --skip Exact ID match only, skip title fuzzy matching
--random Select and launch a random game
-R, --recent Launch the most recently played game
-L, --last Launch the most recently added game
-f, --filter <EXPR> Filter candidate pool by tag, title, or developer (useful with --random)

sena info

Display game card or open associated resources.

sena info <ID> [-g] [-s]
Flag Description
-g, --guide Open linked walkthrough file in $EDITOR
-s, --save Open linked save folder in Windows File Explorer

sena edit

Edit game metadata.

sena edit <ID> [--fetch] [--apply] [-o <N>] [--keep-name]
Flag Description
--fetch Re-fetch metadata from VNDB and open in editor
--apply Apply fetched VNDB metadata directly without opening editor
-o, --order <N> Auto-select Nth VNDB search result
--keep-name Keep existing local title during re-fetch

sena list

List visual novels with formatting and sorting.

sena list [-s <FIELD>] [-r] [-d] [-f <EXPR>]
Flag Description
-s, --sort <FIELD> Sort by: title, lastPlay, createDate, releaseDate, rating, played
-r, --reverse Reverse sort order
-d, --detail Show detailed multi-line cards with tags and paths
-f, --filter <EXPR> Filter query expression

sena stat

Display library aggregate statistics or specific game metrics.

sena stat [ID...] [-f <EXPR>]

sena tl

Display git-log style chronological gameplay timelines.

sena tl [ID...] [--today] [--oneline] [-n <NUM>] [-r] [--no-pager]
Flag Description
--today Display sessions recorded today only
--oneline Condensed single-line output per session
-n, --max-count <N> Limit output to N sessions
-r, --reverse Ascending chronological order
--no-pager Disable terminal pager output

sena rm

Remove a game from the library.

sena rm <ID> [-H, --hard]
Flag Description
(default) Soft removal from local database. Retains cloud assets during sync
-H, --hard Permanent deletion. Records atomic tombstone for cloud synchronization

sena mv

Rename game identifier.

sena mv <OLD_ID> <NEW_ID>

Migrates sessions, local paths, and clears/records appropriate tombstones.


sena sync

Synchronize local library with GitHub repository.

sena sync [--dry-run]
Flag Description
-n, --dry-run Simulate 3-way merge and report changes without modifying local DB or remote repo

sena config

Manage persistent key-value configuration.

sena config [KEY] [VALUE] [-u <KEY>] [-e]
Option Description
(no args) Print all active configuration values
<KEY> Query specific configuration value
<KEY> <VALUE> Set configuration value
-u, --unset <KEY> Delete configuration key
-e, --edit Open all configurations inside $EDITOR

Configuration Reference

SenaVN configuration is stored in SQLite table configs.

Configuration Key Type Default Description
core.editor String Fallback $EDITOR Preferred editor command (e.g. code --wait, nvim, notepad).
fetch.proxy String "" HTTP/HTTPS proxy URL for VNDB queries and cloud sync (e.g. http://127.0.0.1:7890).
sync.repo String "" Target GitHub repository in owner/repo format.
sync.token String "" GitHub Personal Access Token (masked in CLI outputs).
sync.branch String main Git branch storing library synchronization JSON.
sync.path String data.json Path within repository storing library data.