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

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