Dictare / Docs / Installation

Installation

Dictare uses a product-owned runtime store under ~/.local/share/dictare, points ~/.local/share/dictare/current at the active version, and installs the user-facing dictare command in ~/.local/bin.

Homebrew can install the macOS entry point and dependencies, but Dictare owns the runtime after setup.

macOS Install

brew tap dragfly/tap
brew install dictare
dictare setup

Homebrew installs the Dictare entry point, macOS dependencies, and the signed launcher source. dictare setup creates the runtime store, installs the active Dictare runtime, downloads required models, and repairs the service/launcher integration.

Linux Or Direct Install

curl -fsSL https://raw.githubusercontent.com/dragfly/dictare/main/install.sh | bash

The installer:

  1. Creates a dedicated Python 3.11 runtime for Dictare
  2. Installs the latest stable Dictare release into a versioned runtime directory
  3. Creates or updates the current and previous runtime links
  4. Installs the CLI shim at ~/.local/bin/dictare
  5. Installs and starts the background service
  6. Installs the signed macOS launcher at ~/Applications/Dictare.app when running on macOS

Make sure ~/.local/bin is on your PATH.

Upgrade

If Dictare is already installed with the runtime-store installer:

dictare upgrade

Homebrew does not own Dictare runtime upgrades. Use dictare upgrade, not brew upgrade dictare, to update the active runtime.

Release-candidate testers can install the current RC explicitly:

dictare upgrade --version 0.6.0rc1

Rollback is a local runtime switch:

dictare rollback

Then verify:

dictare --version
dictare service status

macOS

Permissions

Dictare needs three permissions on macOS:

  1. Microphone - prompted automatically on first launch
  2. Input Monitoring - required for the global hotkey
  3. Accessibility - required for keyboard mode

After granting permissions, repair the installed service and launcher:

dictare repair

The launcher app lives at ~/Applications/Dictare.app. If Input Monitoring gets stuck, remove Dictare.app from System Settings > Privacy & Security > Input Monitoring, add it again from ~/Applications/Dictare.app, then run dictare repair.

Hotkey

The default hotkey on macOS is Right Command (KEY_RIGHTMETA).

  • Single press: enable/disable microphone
  • Double-tap: submit transcription
  • Right Alt + hotkey: toggle mode (agents/keyboard)

The service plist lives at ~/Library/LaunchAgents/dev.dragfly.dictare.plist.

Linux

The installer supports apt, dnf, and pacman. It does not run sudo automatically; when system packages, groups, or udev rules are missing, it prints the exact command to run and asks you to re-run the installer afterwards.

The default hotkey on Linux is Scroll Lock (KEY_SCROLLLOCK). Your user must be in the input group for global hotkeys:

sudo usermod -aG input $USER

Log out and back in after changing groups.

For keyboard mode on Wayland, install ydotool with your system package manager.

On GNOME with Wayland, you may also need the AppIndicator extension for the tray icon.

Upgrade, Repair, Rollback

dictare upgrade            # Install the latest release and switch to it
dictare repair             # Recreate service files, launcher, and shim
dictare rollback           # Switch back to the previous runtime
dictare service status     # Check if the service is running
dictare service logs       # View service logs

The install and upgrade flow is atomic: a new runtime is prepared first, then current is switched only after the runtime is ready.

Tray App

Start the tray icon manually if your desktop environment does not start it automatically:

dictare tray start

See the Tray App page for details on icon states, menu actions, and troubleshooting.

Development Setup

To run from source without installing:

git clone https://github.com/dragfly/dictare
cd dictare
uv run --python 3.11 dictare service start

All CLI commands work with the uv run --python 3.11 prefix during development.

Uninstall

On Dictare 0.6.0rc1 and newer, remove Dictare runtime/service state while keeping your config and models:

dictare uninstall

For a clean Homebrew-guided reinstall on macOS:

dictare uninstall
brew uninstall dictare
brew install dictare
dictare setup

If dictare uninstall is not available, use the legacy cleanup script:

curl -fsSL https://raw.githubusercontent.com/dragfly/dictare/main/scripts/uninstall.sh | bash

To remove only the background service:

dictare service uninstall

Existing Homebrew Installs

If you installed Dictare before 0.5.0 with the old Homebrew-owned runtime, remove the legacy install first, then install again:

curl -fsSL https://raw.githubusercontent.com/dragfly/dictare/main/scripts/uninstall.sh | bash
brew tap dragfly/tap
brew install dictare
dictare setup

The legacy uninstall script removes the old service, launcher, CLI shims, Homebrew formula links, and runtime files. It does not delete your Dictare config or downloaded models.