Skip to content
The world does revolve around you.

Command line interface#

This page documents the user-facing Ostler commands: the one-shot installer plus the post-install commands it leaves on your PATH.

For the configuration these commands read and write, see Configuration and Environment variables.

Quick reference#

Command Purpose
install.sh One-shot Hub installer
ostler-import Import a GDPR data export folder
ostler-fda Re-run macOS extractors after granting Full Disk Access
ostler-scan-exports Watch ~/Downloads for new GDPR exports
ostler-uninstall Remove Ostler and its data

After installation the commands above live in ~/.ostler/bin, which the installer adds to your shell's PATH by editing ~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish as appropriate.

Installer#

The installer is the signed Mac app a new user runs to set up an Ostler Hub. It is intentionally non-interactive after Phase 2 so the user can step away while it works.

Synopsis#

The customer install path is:

  1. Buy the Hub at ostler.ai/pricing.
  2. The welcome email contains a download link for OstlerInstaller.dmg and a licence file.
  3. Open the DMG, drag OstlerInstaller to Applications, double-click to launch.
  4. The installer prompts for your licence file (drag it in from the email), runs Phase 1 prerequisite checks, asks the Phase 2 questions, and runs unattended through Phase 3 and Phase 4.

Phases#

The installer runs in four phases:

Phase Duration Behaviour
1. Prerequisites seconds Checks macOS version, architecture, RAM, disk
2. Input ~2 minutes Asks the user a small, fixed set of questions
3. Install ~10-15 minutes Unattended; downloads models, sets up services
4. Health check seconds Reports what worked and prints next steps

Exit codes#

Code Meaning
0 Success (or --check passed all checks)
1 Prerequisite failed, user declined a confirmation, or an unrecoverable error

Internal / dev-only: direct install.sh invocation#

The DMG bundles a bash installer (install.sh) that handles the work inside the GUI app. Internal builds and CI runs can call it directly without the GUI wrapper, with the same flags the GUI sets for you:

bash install.sh [--check] [--help] [--licenses] [--allow-plaintext]
Flag Effect
--check Run Phase 1 only. No prompts, no installation. Useful for verifying a machine meets requirements.
--help / -h Print usage and the list of overridable environment variables.
--licenses / --licences Print third-party open-source attributions and exit. After install, reads from ~/.ostler/THIRD_PARTY_NOTICES.md.
--allow-plaintext Dev/CI only. Permit the install to complete without database encryption. Writes a posture marker at ~/.ostler/security-posture/install.json. NOT for production use.
--no-extensions Skip the browser-extensions install phase.

This path is not the supported customer install. It skips the GUI installer's licence gate. Customer installs always come from the DMG via the welcome email.

Re-running the installer#

The installer is idempotent. Re-running it on an existing install detects the existing config (~/.ostler/config/.env) and offers to reuse it. If the security module has already been configured, the encryption setup step is skipped automatically.

A re-run is the supported way to:

  • Repair a partial install
  • Pick up new model versions
  • Refresh launchd services after a macOS upgrade

Environment overrides#

The installer recognises these overrides for advanced or fork-specific deployments. Set them in the shell before running:

Variable Purpose
OSTLER_BETA Skip the invite-code prompt for beta testers
WIKI_OBSIDIAN_DIR Enable Obsidian vault output for the wiki compiler
OLLAMA_HEADLINE_MODEL Override the wiki headline model (default qwen3:8b)

Repository-pinning overrides for forks and private betas are listed in install.sh --help.

ostler-import#

Imports a folder of GDPR data exports (LinkedIn, Facebook, Instagram, Google Takeout, Twitter/X, WhatsApp, etc.) into the Hub.

Synopsis#

ostler-import <exports-dir> [--user-name "Name"] [--verbose]

Arguments and flags#

Argument Required Notes
<exports-dir> yes Directory containing one or more provider exports. The pipeline auto-detects the layout per provider.
--user-name "Name" no Override the display name used during import. Defaults to USER_NAME from ~/.ostler/config/.env.
--verbose no Stream per-record progress to stdout. Useful for diagnosing parsing issues on large exports.

Example#

ostler-import ~/Downloads/gdpr-exports/ \
    --user-name "Alex Example" \
    --verbose

Recognised export shapes#

The export watcher (ostler-scan-exports, run automatically every 4 hours by launchd) detects these patterns under ~/Downloads:

Provider Patterns
LinkedIn Basic_LinkedInDataExport_*/, linkedin_*.zip, LinkedInDataExport_*.zip
Facebook facebook-*/, facebook_*.zip
Instagram instagram-*/, instagram_*.zip
Google Takeout takeout-*.zip, Takeout/
Twitter / X twitter-*/, twitter-*.zip, x-*.zip

When a new export lands the watcher posts a macOS notification telling you to run ostler-import.

Exit codes#

Code Meaning
0 Import completed (check the verbose output for skipped records)
1 Pipeline missing or Python virtualenv not set up – re-run the installer

ostler-fda#

Re-runs the macOS first-party extractors. Use this after granting Full Disk Access to Terminal, or after enabling a new source in OSTLER_FDA_SOURCES.

Synopsis#

ostler-fda

The command takes no arguments. It reads the source-consent list from ~/.ostler/config/.env (OSTLER_FDA_SOURCES) and runs each enabled extractor in turn.

Output#

For each source, the extractor prints one of:

Marker Meaning
[ok] Extracted successfully
[skip] Source disabled in config or unavailable on this Mac
[fail] Extractor errored – usually a missing Full Disk Access grant

Output lands under ~/.ostler/imports/fda/.

Exit codes#

Code Meaning
0 At least one source extracted; per-source failures do not abort the run
1 The extractor module is not installed or the virtualenv is missing

ostler-scan-exports#

Scans ~/Downloads (and adjacent locations) for newly-arrived GDPR exports. Runs automatically every four hours via a launchd job installed at setup; you can also invoke it by hand.

Synopsis#

ostler-scan-exports

The scanner posts a macOS notification when it finds a new export and points you at ostler-import for the actual ingest. It does not import data itself.

Recovery key#

The encryption recovery key is generated during install and is the only way to regain access to your encrypted local databases if you forget the boot passphrase. The current install posture (whether encryption is enabled, when it was set up) is recorded at ~/.ostler/security-posture/install.json.

The recovery key itself is shown once at install time. The installer offers to save it to the macOS Keychain (visible afterwards in the Passwords app); if you decline, you must store it externally. A password manager is the standard choice; a piece of paper in a locked drawer works equally well. We do not have a copy and cannot recreate it.

ostler-uninstall#

Removes Ostler and its local data. Interactive; requires typing YES to confirm.

Synopsis#

ostler-uninstall

What it removes#

  • Docker containers (vector store, graph store, cache)
  • Docker volumes (your knowledge graph data)
  • The ~/.ostler/ directory (except power.conf)
  • All Ostler launchd services (Doctor, export watcher, hub-power, etc.)
  • The Ostler entry in the macOS Keychain (recovery key)

What it does NOT remove#

  • Docker Desktop or Colima
  • Homebrew
  • Ollama or downloaded models (use ollama rm <model-name>)
  • Original GDPR export files in ~/Downloads
  • Your hub power policy at ~/.ostler/power.conf (preserved so a reinstall reuses the same setting)

Reinstalling#

Run the installer again. It will pick up the preserved power.conf and prompt for everything else fresh.

Tips#

Adding the bin directory to your PATH#

The installer modifies your shell rc file once. If you switch shells or want to confirm the entry, look for:

# In ~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish
export PATH="${HOME}/.ostler/bin:${PATH}"

(Fish syntax: set -gx PATH $HOME/.ostler/bin $PATH.)

Diagnostic dashboard#

Browse to http://localhost:8089/doctor after install for a live health view. Doctor is a separate process from the API server and is documented in its own section of the docs site.

Logs#

Stream Path
Installer stdout (capture with tee if you want a copy)
Hub services ~/.ostler/logs/
Hub power ~/.ostler/hub-power.log
Export watcher ~/.ostler/logs/export-scan.log

See also#