Configuration¶

All configuration options for Inkwell.

Overview¶

Inkwell uses YAML configuration files stored in your config directory:

Platform	Location
Linux/macOS	`~/.config/inkwell/`
Windows	`%APPDATA%\inkwell\`

Configuration Files¶

~/.config/inkwell/
├── config.yaml    # Global settings
├── feeds.yaml     # Feed definitions
└── .keyfile       # Encryption key (auto-generated)

Viewing Configuration¶

inkwell config show

Output:

Config file: ~/.config/inkwell/config.yaml
Output directory: ~/podcasts
Log level: INFO
YouTube check: ✓
Transcription model: gemini-2.5-flash
Media cache: enabled, 2048 MB, 30 days

Setting Values¶

Via CLI¶

inkwell config set <key> <value>

Examples:

inkwell config set log_level DEBUG
inkwell config set default_output_dir ~/Documents/podcasts
inkwell config set transcription.api_key "your-key"
inkwell config set cache.media.max_mb 4096

Via Editor¶

inkwell config edit

Opens config.yaml in your $EDITOR (defaults to vi).

All Options¶

General¶

Option	Type	Default	Description
`version`	string	`"1"`	Config format version
`log_level`	string	`INFO`	Logging level (DEBUG, INFO, WARNING, ERROR)
`default_output_dir`	path	`~/podcasts`	Default output directory

Transcription¶

Option	Type	Default	Description
`transcription.api_key`	string	`""`	Google AI API key
`transcription.model_name`	string	`gemini-2.5-flash`	Gemini model for audio transcription
`transcription.youtube_check`	boolean	`true`	Check YouTube for transcripts first

Extraction¶

Option	Type	Default	Description
`max_episodes_per_run`	integer	`10`	Max episodes per batch
`extraction.default_provider`	string	`gemini`	Default LLM provider
`extraction.gemini_api_key`	string	`""`	Optional Google AI key for extraction
`extraction.claude_api_key`	string	`""`	Optional Anthropic key for extraction
`extraction.cache_days`	integer	`30`	Extraction cache duration

Cache¶

Option	Type	Default	Description
`cache.media.enabled`	boolean	`true`	Cache downloaded media/audio files
`cache.media.max_mb`	integer	`2048`	Maximum media/audio cache size in MB
`cache.media.ttl_days`	integer	`30`	Maximum media/audio cache entry age in days

Interview¶

Option	Type	Default	Description
`interview.enabled`	boolean	`true`	Enable interview mode
`interview.auto_start`	boolean	`false`	Auto-start after extraction
`interview.default_template`	string	`reflective`	Default template
`interview.question_count`	integer	`5`	Target questions
`interview.format_style`	string	`structured`	Output format
`interview.max_cost_per_interview`	float	`0.50`	Cost limit
`interview.model`	string	`claude-sonnet-4-5`	Model to use
`interview.guidelines`	string	`""`	Custom guidelines

Obsidian¶

Option	Type	Default	Description
`obsidian.wikilinks`	boolean	`true`	Generate wikilinks
`obsidian.tags`	boolean	`true`	Generate tags
`obsidian.max_tags`	integer	`10`	Maximum tags per note
`obsidian.dataview`	boolean	`true`	Dataview-compatible frontmatter

Example Configuration¶

# ~/.config/inkwell/config.yaml
version: "1"
log_level: INFO
default_output_dir: ~/ObsidianVault/podcasts

# Transcription
transcription:
  api_key: your-google-ai-key-here
  model_name: gemini-2.5-flash   # omit to use the generated config default
  youtube_check: true

# Cache
cache:
  media:
    enabled: true
    max_mb: 2048
    ttl_days: 30

# Extraction
extraction:
  default_provider: gemini
  gemini_api_key: ""  # optional; falls back to transcription.api_key
  claude_api_key: ""  # optional; can also use ANTHROPIC_API_KEY
  cache_days: 30
max_episodes_per_run: 10

# Interview
interview:
  enabled: true
  auto_start: false
  default_template: reflective
  question_count: 5
  format_style: structured
  max_cost_per_interview: 0.50
  guidelines: |
    Focus on practical applications.
    Ask about connections to my work.
    Probe for blog post ideas.

# Obsidian
obsidian:
  wikilinks: true
  tags: true
  max_tags: 10
  dataview: true

Environment Variables¶

Environment variables provide fallback values when the corresponding config key is not set in config.yaml.

Variable	Fallback for
`GOOGLE_API_KEY`	`transcription.api_key` and Gemini extraction
`ANTHROPIC_API_KEY`	Anthropic API key for interview
`INKWELL_CONFIG_DIR`	Config directory location
`INKWELL_OUTPUT_DIR`	`default_output_dir`
`INKWELL_LOG_LEVEL`	`log_level`

Priority for transcription.api_key: Config file value > GOOGLE_API_KEY env var > (error if neither is set)

File Locations¶

Logs¶

~/.local/state/inkwell/inkwell.log

View logs:

tail -f ~/.local/state/inkwell/inkwell.log

Cache¶

~/.cache/inkwell/
├── transcripts/    # Cached transcripts
├── extractions/    # Cached extractions
└── audio/          # Downloaded media/audio cache

Inspect cache:

inkwell cache stats

inkwell cache clear clears cached transcripts only. Media/audio retention is controlled by cache.media.enabled, cache.media.max_mb, and cache.media.ttl_days. See Cache Behavior for the full cache model.

Remove all local cache files manually:

rm -rf ~/.cache/inkwell/

Backup and Restore¶

Backup¶

tar -czf inkwell-backup-$(date +%Y%m%d).tar.gz ~/.config/inkwell/

Restore¶

tar -xzf inkwell-backup-20250101.tar.gz -C ~/

Migration Between Machines¶

Export:

cd ~/.config/inkwell
tar -czf inkwell-export.tar.gz config.yaml feeds.yaml .keyfile

Transfer to new machine

Import:

mkdir -p ~/.config/inkwell
tar -xzf inkwell-export.tar.gz -C ~/.config/inkwell/

Verify:
```
inkwell list
```

Troubleshooting¶

Invalid Configuration¶

✗ Invalid configuration in config.yaml:
  • log_level: Input should be 'DEBUG', 'INFO', 'WARNING', or 'ERROR'

Run 'inkwell config edit' to fix

Solution: Edit config and fix the invalid value.

YAML Syntax Error¶

✗ Invalid YAML syntax in config.yaml:
mapping values are not allowed here
  in "config.yaml", line 3, column 10

Solution: Check YAML syntax (indentation, colons, quotes).

Config Not Found¶

Inkwell creates default config on first run. Force creation:

inkwell config show

Next Steps¶

CLI Commands - Command reference
Troubleshooting - Common issues