Start

This guide walks you through the daily workflow of SenaVN: adding games, linking local paths, managing metadata, launching games, and using the interactive TUI.


1. Adding Games to Your Library

Add games from VNDB using sena add. Provide a title query and a short unique ID for your local library:

# Search VNDB by title and assign a short ID
sena add "gamename" gamename

# Or add using a specific VNDB ID directly
sena add "Steins;Gate" sg --vndb-id v2002

Interactive VNDB Picker

If multiple games match your query, an interactive selection menu appears:

  [1] FORTUNE×WORLD ~Bokura ga Game o Tsukuru Riyuu~ - GLOVETY (Rating: 8.6)
  [2] Itsuka, Todoku, Ano Sora ni. - Lump of Sugar (Rating: 8.4)
Select result [1-2, default 1, q to cancel]

Select the appropriate number or press Enter for the top result.

Metadata Review & File Picker

Unless --skip is passed:

  1. SenaVN opens the fetched metadata in your $EDITOR for manual adjustments.
  2. If no path was provided on the command line, SenaVN opens the interactive terminal file picker to link your game executable immediately.

2. Linking Executable, Save Folder, and Walkthrough

Use sena use to associate local filesystem paths with a game ID. Omit path arguments to trigger interactive terminal browsers starting at your system drive roots:

# Interactively pick executable file (starts at drives root)
sena use gamename

# Interactively pick save folder
sena use gamename --save

# Interactively pick walkthrough / guide file
sena use gamename --guide

# Or pass paths directly
sena use gamename "D:\Games\gamename\gamename.exe" --save "D:\Games\gamename\savedata"

File Picker Controls


3. Launching and Tracking Games

Launch your visual novel with automated background playtime tracking:

# Launch by ID or title query
sena run gamename

# Launch the game you played most recently
sena run --recent

# Launch the most recently added game
sena run --last

# Pick and launch a random game
sena run --random

Live Status & Crash Protection

SenaVN detaches sena-guard.exe to poll the game process PID in the background without holding database locks:

# View currently running games and elapsed session time
sena status

If your game crashes or Windows reboots unexpectedly, the heartbeat file persists. SenaVN automatically reconciles and backfills the session duration on your next CLI command.


4. Viewing & Editing Metadata

# View formatted game info card in terminal
sena info gamename

# Open walkthrough file in your editor
sena info gamename -g

# Open save folder in Windows Explorer
sena info gamename -s

# Edit game metadata in $EDITOR
sena edit gamename

# Refresh metadata from VNDB
sena edit gamename --fetch

5. Using the Interactive TUI

Run sena with no arguments to launch the fullscreen Brick browser:

sena

TUI Controls