Operational commands

These commands let you inspect and maintain the state that notewise builds up over time — statistics, video history, the SQLite cache, and session log files.

`notewise stats`

notewise stats [OPTIONS]

Shows aggregate processing statistics pulled from the local cache: total videos processed, total tokens used, processing time, and per-model breakdowns.

Options

--model

string

Filter the statistics output to a single LLM model string.Default: all models

--since

string

Restrict results to the last N days. Accepts a plain integer (7) or a number suffixed with d (30d).Default: all time

Examples

# All-time stats across all models
notewise stats

# Stats for the last 7 days
notewise stats --since 7

# Stats for a specific model over the last 30 days
notewise stats --model gemini/gemini-2.5-flash --since 30d

`notewise history`

notewise history [OPTIONS]

Lists recently processed videos from the local cache, showing video title, model used, and processing timestamp.

Options

--limit

integer

Maximum number of recent videos to display. Must be at least 1.Default: 10

Examples

# Show the 10 most recent videos
notewise history

# Show the 25 most recent videos
notewise history --limit 25

`notewise info`

notewise info [URL]

When called without a URL, displays runtime information: active config values, state directory paths, cache location, and installed version. When called with a YouTube URL, inspects the source without processing it — resolving video or playlist metadata, available transcript languages, and chapter information.

Examples

# Show runtime info
notewise info

# Inspect a video
notewise info "https://youtube.com/watch?v=VIDEO_ID"

# Inspect a playlist
notewise info "https://youtube.com/playlist?list=PLAYLIST_ID"

notewise info makes live YouTube requests when a URL is provided. It does not use the local cache and does not write any output files.

`notewise doctor`

notewise doctor

Runs a non-destructive health check across your configuration, cache, and log files. It reports on:

Whether a config file exists and is valid
Which API keys are present (masked)
Cache database status and entry counts
Log directory location and recent log files
Any detected issues with paths or permissions

No files are modified. Use this command when something seems wrong before filing a bug report.

notewise doctor

`notewise update`

notewise update

Checks the GitHub releases API for a newer version of notewise. If an update is available, it prints the latest version number and the recommended upgrade command for your install method.

notewise update
# Update available: 1.2.0 (current: 1.0.0)
# Upgrade with one of these commands:
#   uv tool upgrade notewise
#   pipx upgrade notewise
#   pip install --upgrade notewise

If you are already on the latest version, the command confirms it and exits with code 0.

`notewise version`

notewise version

Prints the installed notewise version and exits.

notewise version
# notewise version 1.0.0

`notewise cache`

notewise cache [OPTIONS]
notewise cache SUBCOMMAND [OPTIONS]

Inspects and manages the local SQLite cache database at ~/.notewise/.notewise_cache.db. The cache stores transcript data and processing records so that already-processed videos can be skipped on subsequent runs.

Only one of --info, --show, --clear, or --prune may be passed at a time. Combining them raises an error.

`notewise cache` (or `--info`)

Show cache database metadata: file path, database size, and entry counts.

notewise cache
notewise cache --info

--info

boolean

Show cache database metadata and entry counts. This is the default behavior when no other flag is provided.Default: false

`notewise cache --show VIDEO_ID`

Show the cached metadata entry for a specific video ID.

notewise cache --show dQw4w9WgXcQ

--show

string

Video ID to look up in the cache. Shows the stored metadata for that entry.

`notewise cache --clear`

Delete the entire cache database. You will be prompted to confirm unless --yes is also passed.

# With confirmation prompt
notewise cache --clear

# Skip the confirmation prompt
notewise cache --clear --yes

--clear

boolean

Delete the local cache database.Default: false

--yes

boolean

Skip the confirmation prompt when used with --clear. Has no effect without --clear.Default: false

`notewise cache --prune DAYS`

Remove cache entries older than the specified number of days.

# Prune entries older than 60 days
notewise cache --prune 60

--prune

integer

Remove cache entries older than this many days. Must be 0 or greater. Passing 0 prunes all entries.

Cache subcommands

The same operations are also available as named subcommands:

notewise cache info

notewise cache info

Show cache database metadata and entry counts.

notewise cache show VIDEO_ID

notewise cache show dQw4w9WgXcQ

Show cached metadata for a specific video ID passed as a positional argument.

notewise cache clear [--yes]

notewise cache clear
notewise cache clear --yes

Delete the cache database. Pass --yes to skip the confirmation prompt.

--yes

boolean

Skip confirmation and clear immediately.Default: false

notewise cache prune [--older-than DAYS]

notewise cache prune --older-than 30

Prune stale cache entries by age.

--older-than

integer

Remove cache entries older than this many days. Must be 0 or greater.Default: 30

`notewise logs`

notewise logs [OPTIONS]
notewise logs SUBCOMMAND [OPTIONS]

Lists recent session log files or tails the latest log. Each notewise run writes a timestamped log file to ~/.notewise/logs/.

`notewise logs` (default)

List recent session logs. With --tail, streams the last N lines of the latest log to stdout.

# List recent log files
notewise logs

# Tail the last 50 lines of the latest log
notewise logs --tail 50

# Open the log directory in the system file manager
notewise logs --open

--tail

integer

Print the last N lines of the most recent session log to stdout. Must be at least 1.Default: not set (lists log files instead)

--open

boolean

Open the log directory in the system file manager (Finder, Nautilus, Explorer, etc.).Default: false

`notewise logs clean`

notewise logs clean [OPTIONS]

Prune old log files to reclaim disk space. By default, removes logs older than 7 days.

# Remove logs older than 7 days (default)
notewise logs clean

# Remove logs older than 14 days
notewise logs clean --older-than 14

# Remove all inactive log files regardless of age
notewise logs clean --all

--all

boolean

Remove all inactive log files instead of only those older than the threshold. The active (current) log file is never deleted.Default: false

--older-than

integer

Remove log files older than this many days. Must be 0 or greater. Passing 0 removes all inactive logs (equivalent to --all).Default: 7

Commands

Operational commands

`notewise stats`

Options

Examples

`notewise history`

Options

Examples

`notewise info`

Examples

`notewise doctor`

`notewise update`

`notewise version`

`notewise cache`

`notewise cache` (or `--info`)

`notewise cache --show VIDEO_ID`

`notewise cache --clear`

`notewise cache --prune DAYS`

Cache subcommands

`notewise logs`

`notewise logs` (default)

`notewise logs clean`

Build docs developers (and LLMs) love

Commands

​notewise stats

​Options

​Examples

​notewise history

​Options

​Examples

​notewise info

​Examples

​notewise doctor

​notewise update

​notewise version

​notewise cache

​notewise cache (or --info)

​notewise cache --show VIDEO_ID

​notewise cache --clear

​notewise cache --prune DAYS

​Cache subcommands

​notewise logs

​notewise logs (default)

​notewise logs clean

Build docs developers (and LLMs) love

`notewise stats`

Options

Examples

`notewise history`

Options

Examples

`notewise info`

Examples

`notewise doctor`

`notewise update`

`notewise version`

`notewise cache`

`notewise cache` (or `--info`)

`notewise cache --show VIDEO_ID`

`notewise cache --clear`

`notewise cache --prune DAYS`

Cache subcommands

`notewise logs`

`notewise logs` (default)

`notewise logs clean`