Getting started

Install Samaya, choose a folder for your Org files, and plan your first day. While Samaya is pre-beta, keep a backup of that folder, or keep it in version control. Releases are published at samaya-releases.

Linux · Windows · First run

For x86_64 Linux with glibc 2.36 or newer: Debian 12, Ubuntu 22.04, Fedora, Arch or anything newer.

curl -fsSL https://git.hegdeatri.com/hegdeatri/samaya-releases/raw/branch/main/install.sh | sh

The installer checks the download's checksum, and its signature if minisign is installed. It puts samaya in ~/.local/bin and adds it to your app menu. If ~/.local/bin is not on your PATH, open Samaya from the app menu or run ~/.local/bin/samaya.

On NixOS, see NixOS.

For Windows 10 and 11, x64.

1. Download samaya-1.17.0-x86_64-windows.zip, with its .sha256 and .minisig files from the latest release.

2. Check the hash in PowerShell, and compare it with the .sha256 file:

   Copy

      Get-FileHash .\samaya-1.17.0-x86_64-windows.zip -Algorithm SHA256
   

3. Optionally, check the signature as in Verifying a release.

4. Extract the whole ZIP to a folder and double-click samaya.exe.

No installer or administrator access is needed. The executable has no Windows publisher certificate, so Windows may show an unknown-publisher warning.

Settings are kept in %APPDATA%\samaya and caches in %LOCALAPPDATA%\samaya. Credentials go to Windows Credential Manager. XDG_CONFIG_HOME and XDG_DATA_HOME override the settings and cache locations.

Windows has no tray icon yet. Closing the window quits Samaya and stops syncing, and --hidden opens a regular window. To sync while the app is closed, run .\samaya.exe sync run --watch from PowerShell.

1. Make a folder for your tasks, such as ~/org. An empty one is fine.

2. Open Settings → Org files and choose it. Each .org file in it is a channel, such as work.org or health.org. Create, nest and colour channels in Settings → Channels. See Org files.

3. Plan tasks in Today and Week, then try Focus on one of them.

Everything else is optional:

• Calendars. Settings → Calendars → Connect calendar, then sign in with Google or Microsoft. Nothing needs setting up first. See Google Calendar and Outlook calendars.

• Issues and work items. GitHub, Forgejo, Azure DevOps, Plane and Microsoft Planner.

• Teams status. Microsoft Teams.

• Shortcuts, tray and bar widgets. Desktop integration.

Samaya is one program, samaya:

• samaya opens the app. While it is open it keeps your calendars in sync and shows a tray icon. samaya --hidden starts it in the tray.

• samaya compose opens the task composer; --window pops it up on its own, over whatever is open. See Desktop integration.

• samaya sync sets up calendar accounts and keeps calendar.org current while the app is closed.

Once a day Samaya checks whether a new version is out. When one is, a dot appears beside Settings, and Settings → Update available shows what changed since your version.

• Linux: Update replaces the binary once the release's signature checks out. Restart Samaya to finish. Running the install command again also upgrades.

• Windows: Open downloads opens the releases page. Close Samaya and replace the extracted files with the new release.

What changed in each version is also under Settings → Changelog.

The app syncs calendars only while it is open. To keep calendar.org fresh for org-agenda at other times, run samaya sync run --watch as a systemd user service, ~/.config/systemd/user/samaya-sync.service:

[Unit]
Description=Samaya calendar synchronization
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=%h/.local/bin/samaya sync run --watch
Restart=on-failure
RestartSec=60

[Install]
WantedBy=default.target

systemctl --user enable --now samaya-sync.service

Change ExecStart if samaya is installed somewhere else. While the app is open, samaya sync run exits with an error because the app is already syncing; Restart=on-failure lets the service take over within a minute of the app closing. For a timer instead, see Google Calendar → Syncing from the terminal.

The prebuilt binary does not find its graphics libraries on NixOS by itself. Enable programs.nix-ld and add wayland, libxkbcommon, vulkan-loader and libGL to programs.nix-ld.libraries.

Releases are signed with this key, also in minisign.pub:

RWReXZNuxj5aplTyPD4awKxzs/sL9nlCssugg1Cd9ZbRWrwksTyfsJNe

Keep the .minisig file beside its download, then:

minisign -V -P RWReXZNuxj5aplTyPD4awKxzs/sL9nlCssugg1Cd9ZbRWrwksTyfsJNe \
  -m samaya-X.Y.Z-x86_64-linux.tar.gz

For Windows, use -m samaya-X.Y.Z-x86_64-windows.zip. The trusted comment it prints is the archive's file name. Linux archives are signed from 1.8.0 on.

samaya-sync is now samaya sync, with the same subcommands and flags. Its tray (--tray) is replaced by the app's. Remove the old samaya-sync binary, and change a systemd unit's ExecStart to samaya sync run --watch.

On Linux:

rm ~/.local/bin/samaya ~/.local/share/applications/samaya.desktop \
  ~/.local/share/icons/hicolor/128x128/apps/samaya.png

On Windows, delete the extracted folder. Your Org folder is never touched.