Platform Compatibility
Every Arcana command, file path, environment variable, and shell syntax across Linux, macOS, and Windows. Use this as a quick reference when writing scripts, configuring your environment, or troubleshooting platform-specific issues.
File Paths
Arcana stores configuration and data in your home directory. The base path differs by operating system:
| Resource | Linux | macOS | Windows |
|---|---|---|---|
| Arcana home | ~/.arcana/ | ~/.arcana/ | %USERPROFILE%\.arcana\ |
| Config file | ~/.arcana/config.json | ~/.arcana/config.json | %USERPROFILE%\.arcana\config.json |
| Skills directory | ~/.arcana/skills/ | ~/.arcana/skills/ | %USERPROFILE%\.arcana\skills\ |
| Themes directory | ~/.arcana/themes/ | ~/.arcana/themes/ | %USERPROFILE%\.arcana\themes\ |
| Plugins directory | ~/.arcana/plugins/ | ~/.arcana/plugins/ | %USERPROFILE%\.arcana\plugins\ |
| Memory database | ~/.arcana/memory.db | ~/.arcana/memory.db | %USERPROFILE%\.arcana\memory.db |
| Session data | ~/.arcana/data/sessions/ | ~/.arcana/data/sessions/ | %USERPROFILE%\.arcana\data\sessions\ |
| Cron jobs | ~/.arcana/data/cron-jobs.json | ~/.arcana/data/cron-jobs.json | %USERPROFILE%\.arcana\data\cron-jobs.json |
| Backups | ~/.arcana/.backups/ | ~/.arcana/.backups/ | %USERPROFILE%\.arcana\.backups\ |
| Workspace trust | ~/.arcana/workspace-trust.json | ~/.arcana/workspace-trust.json | %USERPROFILE%\.arcana\workspace-trust.json |
| Proxy key | ~/.arcana/proxy_key | ~/.arcana/proxy_key | %USERPROFILE%\.arcana\proxy_key |
Environment Variables
Environment variables control Arcana behavior without editing the config file. The syntax differs by shell:
Setting Variables
| Variable | Linux / macOS (bash/zsh) | Windows (cmd) | Windows (PowerShell) |
|---|---|---|---|
ARCANA_HOME | export ARCANA_HOME="/opt/arcana" | set ARCANA_HOME=C:\opt\arcana | $env:ARCANA_HOME="C:\opt\arcana" |
ARCANA_VOICE_MODEL | export ARCANA_VOICE_MODEL=small | set ARCANA_VOICE_MODEL=small | $env:ARCANA_VOICE_MODEL="small" |
ARCANA_VOICE_CLEANUP | export ARCANA_VOICE_CLEANUP=true | set ARCANA_VOICE_CLEANUP=true | $env:ARCANA_VOICE_CLEANUP="true" |
ARCANA_VOICE_LANGUAGE | export ARCANA_VOICE_LANGUAGE=en | set ARCANA_VOICE_LANGUAGE=en | $env:ARCANA_VOICE_LANGUAGE="en" |
ARCANA_SKILLS_DIRS | export ARCANA_SKILLS_DIRS="$HOME/.arcana/skills:$HOME/my-skills" | set ARCANA_SKILLS_DIRS=%USERPROFILE%\.arcana\skills;%USERPROFILE%\my-skills | $env:ARCANA_SKILLS_DIRS="$env:USERPROFILE\.arcana\skills;$env:USERPROFILE\my-skills" |
Reading Variables
| Operation | Linux / macOS | Windows (cmd) | Windows (PowerShell) |
|---|---|---|---|
| Print a variable | echo $ARCANA_HOME | echo %ARCANA_HOME% | $env:ARCANA_HOME |
| Check if set | [ -n "$ARCANA_HOME" ] && echo "set" | if defined ARCANA_HOME echo set | if ($env:ARCANA_HOME) { "set" } |
| Unset a variable | unset ARCANA_HOME | set ARCANA_HOME= | Remove-Item env:ARCANA_HOME |
Persistent Variables
To make environment variables persist across terminal sessions:
| Shell | Where to add | Example |
|---|---|---|
| bash | ~/.bashrc | export ARCANA_VOICE_MODEL=small |
| zsh | ~/.zshrc | export ARCANA_VOICE_MODEL=small |
| fish | ~/.config/fish/config.fish | set -gx ARCANA_VOICE_MODEL small |
| PowerShell | $PROFILE | $env:ARCANA_VOICE_MODEL="small" |
| cmd | System Properties > Environment Variables | Add via GUI |
Shell Completions
Arcana ships completions for bash, zsh, fish (Linux/macOS), and PowerShell (Windows):
| Shell | Install command | Target path |
|---|---|---|
| bash | arcana completion bash > ~/.bash_completion.d/arcana | ~/.bash_completion.d/arcana |
| zsh | arcana completion zsh > ~/.zsh/completions/_arcana | ~/.zsh/completions/_arcana |
| fish | arcana completion fish > ~/.config/fish/completions/arcana.fish | ~/.config/fish/completions/arcana.fish |
| PowerShell | arcana completion powershell > "$env:USERPROFILE\Documents\WindowsPowerShell\Modules\Arcana\Arcana.psm1" | $env:USERPROFILE\Documents\WindowsPowerShell\Modules\Arcana\ |
After installing, restart your shell or run the appropriate source command:
- bash:
source ~/.bashrc - zsh:
source ~/.zshrc - fish:
source ~/.config/fish/config.fish - PowerShell:
. $PROFILE
CLI Commands
All arcana CLI commands work identically across platforms. The following commands have platform-specific behavior or output:
| Command | Linux / macOS | Windows | Notes |
|---|---|---|---|
arcana daemon start | Spawns detached process with lock file | Spawns detached process with lock file | Lock file location differs |
arcana daemon stop | Sends SIGTERM to daemon process | Sends termination signal to daemon process | Graceful shutdown on both |
arcana cron add | Uses system cron or Arcana scheduler | Uses Windows Task Scheduler internally | Natural language schedule works on both |
arcana theme set --name | Reads from ~/.arcana/themes/ | Reads from %USERPROFILE%\.arcana\themes\ | Theme file format is identical |
arcana history resume --id | Restores from ~/.arcana/data/sessions/ | Restores from %USERPROFILE%\.arcana\data\sessions\ | Session format is identical |
arcana stats --json | Outputs JSON to stdout | Outputs JSON to stdout | Identical on all platforms |
arcana mcp list | Lists MCP servers from config | Lists MCP servers from config | Config path differs by OS |
arcana memory stats | Reads from ~/.arcana/memory.db | Reads from %USERPROFILE%\.arcana\memory.db | SQLite DB format is identical |
Shell Scripting Patterns
Common patterns that differ between Linux/macOS and Windows:
Error Handling
| Pattern | Bash (Linux/macOS) | PowerShell (Windows) |
|---|---|---|
| Exit on error | set -euo pipefail | $ErrorActionPreference = "Stop" |
| Capture exit code | exit_code=$? | $exitCode = $LASTEXITCODE |
| Switch on exit code | case $exit_code in 0) ... ;; 1) ... ;; esac | switch ($exitCode) { 0 { ... } 1 { ... } } |
| Print to stderr | echo "error" >&2 | Write-Error "error" |
| Pipe JSON to jq | arcana stats --json | jq '.data' | arcana stats --json | ConvertFrom-Json |
File Operations
| Operation | Bash | PowerShell |
|---|---|---|
| Check file exists | [ -f ~/.arcana/config.json ] | Test-Path "$env:USERPROFILE\.arcana\config.json" |
| Create directory | mkdir -p ~/.arcana/skills | New-Item -ItemType Directory -Path "$env:USERPROFILE\.arcana\skills" -Force |
| List files | ls ~/.arcana/themes/ | Get-ChildItem "$env:USERPROFILE\.arcana\themes\" |
| Copy file | cp config.json ~/.arcana/config.json | Copy-Item config.json "$env:USERPROFILE\.arcana\config.json" |
Temp Files
| Operation | Bash | PowerShell |
|---|---|---|
| Temp directory | /tmp/ | $env:TEMP\ |
| Create temp file | mktemp | New-TemporaryFile |
| Screenshot output | /tmp/screenshot.png | $env:TEMP\screenshot.png |
Cron Scheduling
Scheduled tasks differ significantly between Linux/macOS and Windows:
| Schedule | Cron syntax (Linux/macOS) | Natural language (all platforms) |
|---|---|---|
| Every weekday at 9am | 0 9 * * 1-5 | "every weekday at 9am" |
| Daily at 5pm | 0 17 * * * | "daily at 5pm" |
| Weekly on Friday | 0 17 * * 5 | "every Friday at 5pm" |
| First Monday monthly | 0 9 1 * 1 | "first Monday of each month" |
| Every 6 hours | 0 */6 * * * | "every 6 hours" |
Windows note: On Windows, Arcana uses the Windows Task Scheduler internally. Cron syntax is translated automatically. For reliable scheduling on Windows, ensure you are logged in or configure the task to run whether or not you are logged in.
Known Differences
Platform-specific behaviors to be aware of:
| Feature | Linux / macOS | Windows |
|---|---|---|
| Path separator | / | \ (cmd) or / (PowerShell) |
| Case sensitivity | File paths are case-sensitive | File paths are case-insensitive |
| Daemon signals | SIGTERM / SIGINT | Process termination API |
| Cron backend | System cron or Arcana scheduler | Windows Task Scheduler |
| Shell completions | bash / zsh / fish | PowerShell |
| Env var persistence | .bashrc / .zshrc / config.fish | $PROFILE or System Properties GUI |
Platform Compatibility Reference
All Arcana commands work cross-platform. This reference documents the platform-specific differences in file paths, environment variables, shell syntax, and scheduling.
File Paths
Base path: Linux/macOS ~/.arcana/, Windows %USERPROFILE%\.arcana\
Key files: config.json, memory.db, workspace-trust.json, proxy_key
Key directories: skills/, themes/, plugins/, .backups/, data/sessions/
Environment Variables
Set on Linux/macOS: export VAR=value. Set on Windows cmd: set VAR=value. Set on PowerShell: $env:VAR="value".
Multi-value vars use : separator on Linux/macOS, ; on Windows.
Shell Completions
Linux/macOS: arcana completion {bash|zsh|fish}. Windows: arcana completion powershell.
Scheduling
Cron syntax is Linux/macOS only. Use natural language schedules for cross-platform compatibility.
Key Commands
All arcana subcommands are platform-agnostic. Platform-specific behavior: voice setup (model binary), daemon start/stop (process management), cron add (scheduler backend).