Complete Sayl Documentation

This guide covers everything you need to run and configure Sayl, from initial installation to low-level CLI commands, targeting v0.1.0 on Windows.

1. Getting Started & Installation

Sayl currently supports 64-bit Windows 10 and Windows 11.

1. Open the latest GitHub Release and download SAYL-Setup-x64-0.1.0.exe.
2. Launch the installer; it installs inside user scope without requiring administrator elevation.
3. Sayl will be ready in your Start Menu and Desktop shortcuts.

2. Adding a Download

Sayl provides multiple quick ways to start a download:

• Toolbar or shortcut: Click 'Add Download' or press Ctrl + N. If you have a URL in your clipboard, it is pasted automatically.
• Drag and drop: Drag any download link directly from your browser into the Sayl window.
• Duplicate detection: If the link already exists in your tasks, Sayl asks whether you want to reveal the existing task or download it anew, preventing accidental duplicates.

3. Categories & Search

As your downloads grow, Sayl automatically groups them based on file extensions and MIME types:

• 6 Functional Categories: Video, Audio, Documents, Programs, Compressed, and Other for miscellaneous files.
• Status Filters: Switch between All, Active, Paused, Completed, or Failed tasks.
• Live Instant Search: Type in the search box to filter files and URLs in real-time.
• View Modes: Choose between Cards view for rich detail or Table view for dense listing.

4. Progress Window

When downloading, Sayl can show a dedicated progress window providing deep insights into transfer health:

• Parallel Segment Bars: Visual segmented progress bars showing the buffer fill rate of each individual connection.
• Live Metrics: Real-time transfer speed, downloaded vs total size, and estimated time remaining (ETA).
• Direct Actions: Quick buttons to open the finished file or reveal it in Windows Explorer.
• In Settings, you can enable/disable this popup or configure it to close automatically once done.

5. Background Operation & System Tray

Sayl operates quietly in the background without getting in your way:

• Closing or minimizing the window keeps tasks running in the background with an icon in the Windows notification tray.
• Double-clicking the tray icon restores the main application window immediately.
• Right-clicking the tray icon provides quick options to Pause All, Resume All, or Exit completely.

6. Start with Windows

You can configure Sayl to launch automatically on Windows startup. This allows pending downloads to continue automatically whenever you boot up your PC, with negligible memory footprint.

7. Auto-Shutdown on Completion

When downloading large files overnight or before leaving your desk, enable 'Shutdown PC when all downloads complete':

• 30-Second Safety Countdown: Upon completion, Sayl displays a clear 30-second warning dialog with an instant cancel button.
• Strict Safety Guardrails: Shutdown will not trigger if any tasks are paused, failed, or incomplete.

8. Prevent Sleep

Downloads often fail when Windows enters sleep mode after inactivity. Sayl utilizes Windows power APIs to inhibit system sleep while downloads are actively in flight, releasing the lock automatically once tasks finish.

9. Resumption & Server Errors

Sayl is built with strict integrity guarantees for your downloaded files:

• How Resumption Works: Requests byte chunks using HTTP Range requests and validates strong ETag and Last-Modified headers before stitching data.
• Atomic .part Files: Data writes exclusively to a .part file, synced via fsync, and only renamed to the final filename upon 100% verified completion.
• Server Failures: Clear error reporting for expired tokens (403) or server overload (503), retaining downloaded chunks safely.
• Crash Recovery: WAL replay automatically safely sets incomplete tasks to Paused after an unexpected system shutdown.

10. Browser Extension & Setup

The browser extension allows Sayl to capture download links directly from Google Chrome, Microsoft Edge, Brave, and compatible Chromium browsers:

1. Open Sayl, then go to Settings (gear icon or Ctrl+,).
2. Navigate to the Browser Extension section and click Activate.
3. Your browser will open the official extension store page; click Add to browser.

Once installed, Sayl captures downloads seamlessly, and you can right-click any link to choose 'Download with Sayl'.

11. Command-Line Interface (sayl CLI)

Sayl includes a high-performance standalone CLI (sayl.exe) providing full programmatic control:

Core Commands:

Global Options:

Exit Codes:

0: Success · 2: Usage error · 3: Task failed · 4: Cancelled · 5: Store or I/O error.

12. Settings Option by Option

Open settings anytime by clicking the gear icon or pressing Ctrl + ,. Here is what each option controls:

Keyboard Shortcuts:

• Ctrl + N: Add a new download and auto-paste URL.
• Space: Pause or resume selected task.
• Delete: Cancel or remove selected task.
• Ctrl + O: Open Downloads directory in Windows Explorer.
• Ctrl + ,: Open settings dialog.
• Esc: Close dialog or cancel input.

13. Data Storage Locations

Sayl keeps its data transparent and self-contained on your PC:

• Settings & Store: Saved in standard Windows app data:
  %APPDATA%\SAYL\
  containing settings.json and the store\ directory.
• Completed Files: Located in %USERPROFILE%\Downloads\ or your custom directory.
• Partial Files (.part): Kept next to download destination until 100% complete.
• Complete Cleanup: To erase all data, simply delete %APPDATA%\SAYL\.

14. Building Sayl from Source

Sayl is 100% open-source; you can compile and audit it locally:

1. Prerequisites:
   • Windows 10/11 x64
   • Rust GNU toolchain: stable-x86_64-pc-windows-gnu
   • Node.js 18+ with npm
2. Setup Environment in PowerShell:
   $env:RUSTFLAGS = "-C linker=rust-lld"
3. Run Checks and Test Suite:
   cargo check --workspace
cargo test --workspace
4. Build Desktop UI (Tauri):
   cd apps/desktop
npm install
npm run tauri build

15. Contributing Code

Contributions are welcome. Before submitting a Pull Request, please ensure:

• All deterministic workspace tests pass cleanly via cargo test --workspace.
• Code is formatted according to standard formatting using cargo fmt --all.
• Use standard imperative commit messages (e.g., fix(http): handle chunk timeout gracefully).
• Consult CONTRIBUTING.md in the repository for full guidelines.

16. Reporting Issues

If you encounter a bug or unexpected behavior:

• General Bugs & Features: Open an issue on GitHub Issues using our issue templates.
• Security Vulnerabilities: Please report security concerns privately per the instructions in SECURITY.md.

17. Plugins

18. Themes

19. Frequently Asked Questions