BYOAO Guide

CLI Reference

4 min read

CLI Reference

All BYOAO command-line commands.

byoao install

Register the BYOAO plugin in OpenCode and install Obsidian Skills.

byoao install              # Interactive — asks location + skills
byoao install -y -g        # Non-interactive, global install
byoao install --no-skills  # Skip Obsidian Skills
FlagDescription
-g, --globalInstall globally (all projects)
-y, --yesSkip interactive prompts
--no-skillsSkip installing Obsidian Skills
--project-dir <path>Project directory (default: cwd)

byoao uninstall

Remove the BYOAO plugin from OpenCode. Vaults and notes are not affected.

byoao uninstall
byoao uninstall -g -y    # Non-interactive, global
FlagDescription
-g, --globalUninstall from global config
-y, --yesSkip confirmation
--project-dir <path>Project directory (default: cwd)

byoao init

Create a new knowledge base or adopt an existing folder.

# Interactive (recommended)
byoao init
 
# Adopt existing folder
byoao init --from ~/Documents/my-notes
 
# Non-interactive with flags
byoao init --kb "My KB" --name "Jay" --preset pm-tpm
FlagDescription
--kb <name>Knowledge base name (required in non-interactive mode)
--name <name>Your name (default: OS username)
--path <path>Vault location (default: ~/Documents/{kb name})
--from <path>Adopt an existing folder as a knowledge base
--preset <name>Preset: minimal (default) or pm-tpm
--provider <name>AI provider: copilot, gemini, or skip
--gcp-project <id>GCP Project ID (required with --provider=gemini)

Interactive preset flow: If you do not pass --preset, the CLI asks for main use (Personal vs Work), then (for Work) may offer a work setup list when multiple presets apply. Passing --preset skips those questions and locks the preset for this run.

Mode detection:

  • Empty or non-existent path → Mode A (fresh KB)
  • Path with .md files → Mode B (adopt existing, confirms with user)
  • Path with .obsidian/ → Mode B with .obsidian/ preservation

byoao status

Check the health of a vault: agent page count by type, broken links, INDEX.base completeness.

byoao status              # Check current directory
byoao status ~/my-kb      # Check specific path
ArgumentDescription
[path]Vault path (default: current directory)

byoao upgrade

Upgrade the BYOAO CLI and vault infrastructure (OpenCode skills under the vault’s .opencode/skills/, Obsidian plugin config, etc.) to the latest version. If ~/.config/opencode/skills already exists (from a prior byoao install -g), a successful vault upgrade also refreshes that global skills directory from the current package so it does not go stale. Root AGENTS.md / SCHEMA.md are not overwritten; use byoao sync-docs to merge missing template sections into existing vaults.

The command runs in two phases: first it checks for a newer CLI version on npm and offers to update it, then it upgrades the vault content. If the CLI is updated, the process exits and you run byoao upgrade again to complete the vault upgrade.

byoao upgrade             # Upgrade CLI + vault in current directory
byoao upgrade ~/my-kb     # Upgrade CLI + specific vault
byoao upgrade --dry-run   # Preview changes without applying
byoao upgrade --skip-cli  # Only upgrade vault, skip CLI update
FlagDescription
-y, --yesSkip confirmation prompts
--dry-runShow plan without executing
--forceRun even if versions match (re-copy vault skills; still syncs global ~/.config/opencode/skills when present)
--skip-cliSkip CLI self-update, only upgrade vault
--preset <name>Override preset during bootstrap

byoao sync-docs

Insert packaged sections into vault-root AGENTS.md and SCHEMA.md when they are missing (for example Knowledge Retrieval (Q&A) and Retrieval). Safe merge: does not replace whole files or delete your edits. Run from the vault root (or pass the vault path).

byoao sync-docs              # Current directory vault
byoao sync-docs ~/my-kb      # Specific vault
byoao sync-docs --dry-run    # Show what would change; no writes
FlagDescription
--dry-runPreview only; do not modify files

Note: AGENTS.md must contain a ## Available Skills heading so the tool knows where to insert the retrieval block. If you removed or renamed it, merge manually from the package templates.

byoao check-obsidian

Verify that Obsidian is installed and running.

byoao check-obsidian

Reports: installed (yes/no), running (yes/no), version, vaults directory.

byoao logs

View and manage BYOAO error logs. Errors from tools, hooks, and CLI commands are automatically recorded to ~/.byoao/logs/error.log.

byoao logs                # Show recent 20 entries
byoao logs --tail 50      # Show recent 50 entries
byoao logs --json         # Output raw JSON (for scripting)
byoao logs --export ~/Desktop/byoao-logs.txt   # Export to file
byoao logs --clear        # Clear all logs
FlagDescription
--tail <n>Number of recent entries to show (default: 20)
--export <path>Export logs to a file (includes system info header)
--clearClear all log files
--jsonOutput entries as raw JSON lines

Export format: The exported file includes a header with BYOAO version, Node version, and OS info — useful when sharing logs for debugging.

Backlinks