Get started with the OwAI CLI

OwAI without a desktop window

The CLI (command-line interface) runs OwAI from a terminal on your Mac, Linux computer, or compatible home server. It is useful when your media lives on a computer that stays on, or when you want an AI assistant to manage that library without leaving a desktop window open. Docker is optional, not required.

This is the same library engine as the desktop app: it watches folders, indexes photos and video frames, detects faces when enabled, and handles organization and recovery. It does not provide a browser-based photo gallery. Use the desktop app if you prefer a visual interface; use MCP to search and organize the server library with an assistant.

Start with a small test folder and keep a backup. Adding a folder does not move or optimize your originals. Later actions such as deleting, restoring or exporting files can change the media on disk.

• Prefer a window? Download the desktop app
• Agent and command reference

What you need — and what costs money

Native packages support macOS 13.4 or newer (Apple Silicon or Intel) and Linux x64/ARM64 with glibc 2.35 or newer, such as Ubuntu 22.04 or Debian 12. The Bash installer does not install a Windows CLI. Some NAS systems use a different Linux runtime and cannot run these packages directly.

You need Bash, curl, tar, and sha256sum or shasum. The review step below also uses the less text viewer. Install FFmpeg separately if you want to index videos. Linux also needs its standard C/C++ runtime and liblzma. The OwAI installer does not run sudo or install system packages for you.

• Current pricing and credit details

1. Install and follow the setup questions

Download the official installer with the command below. The next command opens it for review; press q to close the viewer. The installer runs only if the download and review commands succeed.

Setup asks where to keep the library data, whether to use free local or paid hosted processing, which media folder to add, whether to detect faces, whether to download models, and whether to start a background service. You can decline downloads, paid processing and background startup. Local models require more than 1 GB of downloads. Choose a data directory separate from the desktop app's library.

• The launcher is normally installed at ~/.local/bin/owai. Add ~/.local/bin to your shell's PATH if owai is not found, or run it by its full path.
• If setup created your profile and started the service, skip the manual setup below and go to Check that it is working.
• If you decline automatic setup, follow the manual steps below. Installing the executable by itself does not start indexing.

cli_installer="$(mktemp)" &&
curl --fail --proto '=https' --tlsv1.2 \
  --output "$cli_installer" https://release.organizewith.ai/install.sh &&
less "$cli_installer" &&
bash "$cli_installer" --setup

2. Manual setup: create a library and add a folder

Skip this step if guided setup already created your library. A profile is the directory where OwAI saves its database, models, settings and processing queue — not the directory containing your original photos. This example uses a separate directory in your home folder. Keep it on a local disk, not an NFS or SMB network share.

Replace /absolute/path/to/photos with a real folder readable by your user, keeping the quotes around paths with spaces. The --detect-faces flag enables face detection for this folder; omit it if you do not want faces processed. The folder is registered now and processed when you start the service.

• If init says the profile already exists, do not delete it. Continue with status or config using that directory.
• The profile path must be supplied in every terminal session, either through ORGANIZER_APP_DATA_DIR or --data-dir. OwAI never guesses your desktop library.
• Only one desktop app or CLI service may own a profile at a time. Do not run two independent profiles against the same originals for write/delete workflows.

export ORGANIZER_APP_DATA_DIR="$HOME/.local/share/owai/library"
owai init
owai folders add "/absolute/path/to/photos" --name "Photos" --detect-faces

3. Download local models and start processing

For free local processing, download the models while the service is stopped. You need Internet access for this download. The all option includes search, image/video-frame indexing and face models. Downloading a face model does not enable face detection for folders by itself.

serve keeps running in this terminal. It scans registered folders, processes the queue and watches for changes. Keep this terminal open, or use the background service option described below. Press Ctrl+C to stop gracefully; unfinished queued work is preserved for the next start.

owai models download all
owai serve

4. Check that it is working

Open a second terminal and point it to the same profile. health should report ready: true. status returns a structured report (JSON) with settings, folders, queue, models and sync status. A running service is not the same as completed indexing: check the folder and queue information before trying semantic searches.

folders list shows the actual folder IDs. To request another scan, run owai scan followed by one of those IDs. Scheduling a scan is not proof that processing has finished.

export ORGANIZER_APP_DATA_DIR="$HOME/.local/share/owai/library"
owai health
owai status
owai folders list
owai models status

5. Connect an assistant

For an assistant running on this computer that accepts stdio MCP configurations, run owai mcp-config and use the generated configuration in the assistant. It contains the executable and profile paths. Keep owai serve running. The mcp command connects to that existing service; it does not start another indexer.

For a browser or remote assistant, connect https://index.organizewith.ai/mcp using the normal OwAI OAuth flow. The server must be connected to the same paid OwAI account, with Cloud index sync enabled and initial sync complete. Remote search reads the synced index; queued library changes need the owning service online.

To let an assistant see photo or video-still previews, additionally enable Remote media access on the owner. It is off by default. Media is relayed on demand, not backed up to cloud storage. A headless server does not offer open_media to open desktop windows; assistants use read_media for previews instead.

There is no owai search shell command. Search, collections, groups, people and reviewed duplicate actions are available through the same MCP tools used with the desktop app.

owai mcp-config

• Set up credentials and optional cloud access
• Connect your AI assistant

Connect a OneDrive library

OneDrive is a two-way cloud library, not a mandatory download folder. Connect your OwAI account with Cloud Access first, then start Microsoft sign-in below. Enter the code from your own terminal at Microsoft's verification page and poll the returned session ID at the reported interval. Use drive, folder and source IDs returned by browse and status, not filenames or guessed IDs.

Local indexing uses this host's models and temporarily downloads originals; keep serve running. Indexing and face detection follow the profile settings. Cloud indexing uses inference credits and continues when this host is off only when indexing and any enabled face processing are both cloud-based. Mixed processing requires this host online. Enable --detect-faces only if you want face processing. Originals stream by default, while small OneDrive thumbnails are cached. --retain-originals enables an optional bounded local cache, not a guaranteed full offline backup.

Collections, groups, people, favorites and duplicate actions use the same MCP tools as local folders. OneDrive edits commit on the index server and replicate to app/CLI. Remote MCP can read provider previews without an online desktop or desktop relay. Exports and generated images go to OneDrive/OwAI by default; onedrive download saves an explicit new local copy. Deletion uses Microsoft's recycle bin and retention policy, not OwAI's local 30-day recovery.

• Without Internet, cached media and replicated metadata remain browsable; uncached files, cloud edits and OneDrive semantic search need a connection. Local-folder search remains available offline.
• Removing a source never deletes its OneDrive files. Disconnect forgets the Microsoft grant; reconnect the same account to resume. Work accounts may require admin consent. Shared-folder shortcuts and SharePoint browsing are not supported.
• Use owai onedrive SUBCOMMAND --help for exact options. Wait for indexing and tracked file operations to finish before reporting success.

owai onedrive connect
owai onedrive poll SESSION_ID
owai onedrive browse
owai onedrive browse --drive DRIVE_ID
owai onedrive browse --drive DRIVE_ID --item FOLDER_ID
owai onedrive add DRIVE_ID FOLDER_ID --detect-faces
owai onedrive status
owai onedrive sync SOURCE_ID
owai onedrive cache SOURCE_ID --retain-originals --limit-gib 20
owai onedrive download ASSET_ID /absolute/path/new-photo.jpg

• Connect your OwAI account
• OneDrive setup and behavior

Keep it running in the background

The easiest option is to accept the background-service step in guided setup. On Linux it installs a systemd user service; on macOS it installs a LaunchAgent. These run as your user, not root. A macOS LaunchAgent runs while that user is logged in. Linux user services may stop at logout unless an administrator explicitly configures lingering or a system service.

For an existing profile, the installed package includes share/service.sh. Use the actual package and executable paths printed by the installer in the example below. Stop a foreground owner first. Without --start, the script only writes the service configuration. With --start, it starts or restarts the service and begins queued processing.

• Linux: stop/restart with systemctl --user stop owai or systemctl --user restart owai. View logs with journalctl --user -u owai.service.
• macOS: the service is ai.organizewith.owai-headless in your launchctl user domain; its logs are in the profile's logs/service.log. Use the service instructions in the agent reference for exact stop/start commands.
• For a paid setup, add --key-file /absolute/path/to/owai-key to service.sh. It is a file path, never the secret itself.

bash "/absolute/path/to/installed-release/share/service.sh" \
  "/absolute/path/to/installed-release/bin/owai" \
  --data-dir "$HOME/.local/share/owai/library" --start

• Service and upgrade reference

Common problems

• CLI command and troubleshooting reference
• Contact support