# sync specific folder\naethel pull --all -m \"initial pull\" # hydrate local files from the current remote tree\n```\n\n> `credentials.json` and `token.json` are local secrets — never commit them.\n\n## Daily Workflow\n\n![\"Aethel](\"docs/demo.png\")
\n\nWatch the animated version on the website.
\n\nAethel is not a background mirror. It uses a Git-like flow:\n\n```text\nsnapshot -> status/diff -> add/resolve -> commit\n```\n\n`status`, `add`, `pull`, and `push` compare three states: the latest Aethel\nsnapshot, Google Drive, and your local files. A successful `commit`, `pull`, or\n`push` saves a new snapshot for the operations it applied. Remote changes that\nthis device has not applied retain their previous baseline, including renames\nand deletions from another device. Normal commands refresh Drive observations\nbefore comparing changes.\n\nScheduled `pull` and `push` runs can use `--non-interactive` to prevent browser\nauthentication. Without `--force`, conflicts remain unresolved while unrelated\nchanges can proceed; the command exits with code 2 when conflicts are detected.\nStaged execution failures exit with code 3. Transfer progress is also written to\nstderr when output is redirected, so scheduled runs report their progress.\n\n### Commit Recovery\n\nA commit checkpoints completed operations even when other operations fail.\nFailed entries remain staged. If snapshot saving fails, the next `aethel commit`\nuses `.aethel/execution.jsonl` to finish checkpointing without replaying completed\ntransfers. This also works when no entries remain staged.\n\nThe workspace execution lock is `.aethel/sync.lock`. Concurrent commits are\nrejected. A terminated process can leave this lock behind: its owner PID and\nhostname must be checked before an operator removes it. An interrupted operation\nwithout a durable outcome stops with `RECOVERY_REQUIRED`; its effects need to be\nreconciled before retrying. The execution journal must be preserved for that\nreview. Recovery does not yet automatically resolve these ambiguous outcomes.\n\n### Diagnostic Logs\n\nCommands run inside an initialized workspace write JSON-lines logs under\n`.aethel/logs/`. Each run has a unique ID; operation events include an operation\nID, action, path, outcome, and sanitized error. State comparisons record cache\nusage, conflict counts, and timings. Baseline saves are recorded separately.\n\nCompleted runs use `.jsonl`; running or interrupted runs use\n`.active.jsonl`. The next run removes completed logs beyond the newest\n20 files or seven days, and abandoned active files older than seven days.\nEach file is capped at 5 MiB, with space reserved for its final outcome.\nAfter the cap is reached, intermediate events are omitted and\n`log.limit_reached` records the omission.\n\nLogs exclude file contents and API request/response bodies, redact known\ncredential fields and URLs, and use restrictive permissions where supported.\nThey contain file names and paths, so review them before sharing. Logging\nfailures produce one stderr warning per run and do not interrupt synchronization.\nThese logs support diagnosis; they are not a transaction journal for recovery.\n\n### Review Changes\n\n```bash\naethel status # local vs remote changes at a glance\naethel status --short # compact Git-style status\naethel status --detail # show every file-level change\naethel diff --side all # show local and remote changes\naethel diff --side all --detail # include hashes and modified times\n```\n\nBy default, `status` groups many file-level changes under the nearest changed\nparent folder. Use `--detail` when you need to inspect every changed file.\n\n### Sync Both Ways Manually\n\n```bash\naethel add -A # stage default suggested actions\naethel diff --staged # review what will be applied\naethel restore --staged # unstage like git restore --staged\naethel commit -m \"sync\" # execute staged operations\n```\n\nThis is the safest workflow when both Drive and local files may have changed.\n\n### Pull From Drive\n\n```bash\naethel fetch # refresh and preview remote changes\naethel pull -m \"pull\" # apply remote changes since the last snapshot\naethel pull --all # download the full remote tree\naethel pull path/to/folder # pull only matching paths\n```\n\nUse `pull --all` for a first full download or when you intentionally want to\nrehydrate local files from the current Drive tree.\n\n### Push To Drive\n\n```bash\naethel push -m \"push\" # apply local changes to Drive\naethel push path/to/folder # push only matching paths\naethel push --dry-run # preview local changes before upload/delete\naethel push --force # make local state authoritative\n```\n\n`push --force` accepts local versions for conflicts and treats Drive-only files\nas remote deletions when they do not exist locally. Use `--dry-run` first when\nyou are cleaning up a large remote tree.\n\n### Resolve Conflicts\n\nWhen both sides change the same path, Aethel stops and asks you to choose:\n\n```bash\naethel status\naethel resolve --keep local path/to/file # upload local version\naethel resolve --keep remote path/to/file # download Drive version\naethel resolve --keep both path/to/file # keep both copies\naethel commit -m \"resolve conflict\"\n```\n\nGit-style aliases also work:\n\n```bash\naethel resolve --ours path/to/file # same as --keep local\naethel resolve --theirs path/to/file # same as --keep remote\naethel resolve --both path/to/file # same as --keep both\n```\n\n### Inspect History And Remote\n\n```bash\naethel remote -v # show the Drive remote as origin\naethel log --oneline # compact sync history\naethel show --stat HEAD # snapshot summary\naethel rev-parse --short HEAD # resolve snapshot refs\n```\n\n### Branches And Tags\n\nBranches and tags are lightweight names for Aethel snapshots. Switching a branch\nchanges the active snapshot ref; it does not rewrite your working files by\nitself.\n\n```bash\naethel branch -v # show branch refs and Drive target\naethel switch -c experiment # create and switch branch refs\naethel checkout experiment # switch to a branch when the name exists\naethel tag v1 HEAD # name a snapshot for later inspection\naethel restore --source v1 path/to/file\n```\n\n## Maintenance Commands\n\n### Verify Integrity\n\n```bash\naethel verify # check snapshot checksum and local file hashes\naethel verify --remote # also compare Drive file hashes\n```\n\n`verify` compares the latest snapshot with the workspace on disk and exits\nnon-zero when files are missing or modified. Add `--remote` when you also want\nto verify Drive state before a migration or restore.\n\n### Clean Ignored Files On Drive\n\nIgnored local files are skipped by normal sync scans. If ignored build artifacts\nor cache files already exist on Drive, clean them explicitly:\n\n```bash\naethel clean --ignored\naethel clean --ignored --execute --confirm \"DELETE IGNORED GOOGLE DRIVE FILES\"\n```\n\nThe command dry-runs by default and reports the topmost ignored Drive\nfiles/folders it would move to trash. Add `--permanent` only when you really\nwant Drive items deleted instead of trashed.\n\n### Deduplicate Drive\n\nMulti-device conflicts can leave duplicate folders on Drive:\n\n```bash\naethel dedupe-folders # dry run — report only\naethel dedupe-folders --execute # merge duplicates, trash empties\n```\n\nProcesses deepest-first for single-pass convergence, caches child state to minimize API calls, and runs independent merge groups in parallel.\n\n## Commands\n\n| Command | What it is for |\n| --- | --- |\n| `auth` | Sign in to Google Drive |\n| `clone` | Create a workspace from a Drive folder and download its contents |\n| `init` | Connect an existing local directory to My Drive or a Drive folder |\n| `status` | Show remote, local, staged, and conflicted changes |\n| `diff` | Inspect unstaged or staged changes |\n| `add` | Stage suggested sync actions |\n| `reset` / `restore --staged` | Unstage changes |\n| `commit` | Execute staged sync actions and save a snapshot |\n| `fetch` | Refresh remote state without applying it |\n| `pull` | Apply Drive changes locally |\n| `push` | Apply local changes to Drive |\n| `resolve` | Choose local, remote, or both for conflicts |\n| `log` / `show` / `rev-parse` | Inspect saved snapshots |\n| `branch` / `switch` / `checkout` / `tag` | Name and switch snapshot refs |\n| `rm` / `mv` | Git-like local remove and rename helpers |\n| `ignore` / `clean --ignored` | Manage ignored paths and remove ignored files from Drive |\n| `verify` | Check local and optional remote integrity |\n| `dedupe-folders` / `dedupe-files` | Clean up duplicate Drive entries |\n| `tui` | Open the interactive terminal UI |\n\n### Git-Compatible Command Forms\n\nAethel is not Git: `commit` applies Drive sync operations and writes an Aethel\nsnapshot, while Google Drive is the remote storage. The daily command shape is\nintentionally close to Git:\n\n| Git habit | Aethel form |\n| ---------------------------- | ------------------------------------------------ |\n| `git status --short` | `aethel status --short` or `aethel status -s` |\n| `git diff --staged` | `aethel diff --staged` or `aethel diff --cached` |\n| `git add -A` | `aethel add -A` |\n| `git reset HEAD ` | `aethel reset HEAD ` |\n| `git restore --staged `| `aethel restore --staged ` |\n| `git commit -m \"message\"` | `aethel commit -m \"message\"` |\n| `git log --oneline` | `aethel log --oneline` |\n| `git show --stat HEAD` | `aethel show --stat HEAD` |\n| `git rev-parse HEAD` | `aethel rev-parse HEAD` |\n| `git rev-parse --short HEAD` | `aethel rev-parse --short HEAD` |\n| `git rev-parse --abbrev-ref HEAD` | `aethel rev-parse --abbrev-ref HEAD` |\n| `git branch -v` | `aethel branch -v` |\n| `git branch feature HEAD` | `aethel branch feature HEAD` |\n| `git switch feature` | `aethel switch feature` |\n| `git switch -c feature` | `aethel switch -c feature` |\n| `git checkout feature` | `aethel checkout feature` |\n| `git checkout -b feature` | `aethel checkout -b feature` |\n| `git tag v1 HEAD` | `aethel tag v1 HEAD` |\n| `git remote -v` | `aethel remote -v` |\n| `git clone ` | `aethel clone ` |\n| `git restore --source [` | `aethel restore --source ][ ` |\n| `git checkout -- ` | `aethel checkout ` |\n| `git pull` / `git push` | `aethel pull` / `aethel push` |\n\nExisting long Aethel forms such as `add --all` and `reset --all` remain\nsupported.\n\n## TUI\n\n```bash\naethel tui\n```\n\nDual-pane file browser — local filesystem on the left, Google Drive on the right.\nThe local pane watches the current directory, so edits, renames, and deletes show\nup without a manual reload. Successful Drive trash/delete actions also update the\npane immediately while Aethel reloads the authoritative Drive listing.\n\n| Key | Action |\n| -------------------- | -------------------------------------------------- |\n| `Tab` | Switch panes |\n| `Left` / `Right` | Navigate up / into directories |\n| `u` | Upload selected local file or folder to Drive |\n| `s` | Batch sync local folder to current Drive directory |\n| `U` | Upload from a manually entered path |\n| `n` | Rename selected local item |\n| `x` | Delete selected local item |\n| `Space` | Toggle selection in Drive pane |\n| `t` / `d` | Trash / permanently delete selected Drive items |\n| `/` | Filter by name |\n| `f` | Open the commands page and choose a TUI action |\n| `:` | Run any Aethel CLI command inside the TUI |\n| `r` | Reload local and Drive panes |\n\n## Directory Packing\n\nLarge directories with many small files (e.g., `node_modules`, `vendor`) can be slow to sync. Aethel can pack these into compressed archives for faster transfers.\n\n### Enable Packing\n\nCreate `.aethelconfig` in your workspace root:\n\n```yaml\npacking:\n enabled: true\n compression:\n default:\n algorithm: gzip # gzip, brotli, zstd, xz, or none\n level: 6\n rules:\n - path: node_modules\n strategy: full\n - path: vendor\n strategy: full\n```\n\n### How It Works\n\n1. **Tree Hash**: Directories are fingerprinted using mtime+size (30x faster than MD5)\n2. **Pack Detection**: `aethel status` shows pack states (P+, PL, PR, P=, P!)\n3. **Compression**: Archives use gzip/brotli (built-in) or zstd/xz (if installed)\n\n### Pack Status Codes\n\n| Code | Meaning |\n|------|---------|\n| `P+` | New pack (not yet synced) |\n| `PL` | Pack changed locally |\n| `PR` | Pack changed on Drive |\n| `P=` | Pack up to date |\n| `P!` | Pack conflict |\n\nUse `aethel status --verbose` to show synced packs.\n\n## Ignore Patterns\n\nCreate `.aethelignore` (gitignore syntax) in your workspace root — or run `aethel init` to generate a default one.\n\n```gitignore\n# Python virtual environments\n.venv\n.venv-*\n.venv_*\nvenv\nvenv-*\nvenv_*\nenv\nenv-*\nenv_*\nENV\nENV-*\nENV_*\nuv-cache\nnode_modules/\n__pycache__/\n.idea/\ndist/\nbuild/\n```\n\nIgnored paths are skipped by normal sync scans. Use `aethel ignore list` to\nsee active patterns and `aethel ignore test ` to check one path.\n\n## Environment Variables\n\n| Variable | Default | Description |\n| ------------------------------- | ----------------------------------- | ------------------------------------------------ |\n| `GOOGLE_DRIVE_CREDENTIALS_PATH` | `~/.config/aethel/credentials.json` | Path to OAuth credentials |\n| `GOOGLE_DRIVE_TOKEN_PATH` | `~/.config/aethel/token.json` | Path to cached OAuth token |\n| `AETHEL_DRIVE_CONCURRENCY` | `40` | Max concurrent Drive API requests |\n| `AETHEL_TRANSFER_CONCURRENCY` | `32` | Max concurrent upload/download/delete operations |\n\n## How It Works\n\nAethel keeps its workspace state in `.aethel/` and records the latest successful\nsync as a snapshot. Each status or sync command compares that snapshot with the\ncurrent Drive tree and the current local tree, so it can tell the difference\nbetween remote changes, local changes, deletions, and true conflicts.\n\nFor implementation details, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}]