> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pnbr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Synced folder

> A synced folder keeps one collection current from a folder on a computer, a Google Drive folder or Granola notes. The folder is the authority, and its Files cannot be changed in Penumbra.

Concept · files

> **Use when**
>
> The person wants a collection to follow a folder, a vault or a notes account, or you must check, pause or stop one.

> **Looking for something else?**
>
> One-off uploads of documents (recipe [bring-in-a-corpus](https://docs.pnbr.io/guides/bring-in-a-corpus.md)). A newer copy of one document (recipe [new-edition](https://docs.pnbr.io/guides/new-edition.md)). Grouping Files without a folder behind them (card [collection](https://docs.pnbr.io/concepts/collection.md)).

## For

A synced folder ties one collection to a place that keeps its own documents.
The place is a folder or Obsidian vault on a computer, a folder in Google
Drive, or the notes of a Granola account. Penumbra brings each document in as a
File. A change in the folder becomes a new version of the same File. A renamed
document keeps its File. A deleted document goes to Trash.

The folder is the authority. Its Files read as ordinary Files, with versions,
passages and search, but Penumbra refuses to change them. To change one, change
the document in its folder, or stop syncing.

## Use when

* The person has a folder, a vault or a notes account that changes, and wants
  Penumbra to follow it.
* You must see whether a synced folder is up to date, and what its last run
  changed.
* A File refuses a change and says it is kept in sync with its folder.
* The person wants to pause, resume or stop syncing.

## Not this

* Documents that you add once: use recipe [bring-in-a-corpus](https://docs.pnbr.io/guides/bring-in-a-corpus.md).
* A newer copy of one document: use recipe [new-edition](https://docs.pnbr.io/guides/new-edition.md). A synced File takes
  its new editions from the folder (rule [source.1](https://docs.pnbr.io/concepts/source.md#rule-source-1)).
* Files that you group by hand: use a collection (card [collection](https://docs.pnbr.io/concepts/collection.md)).

## Rules

1. `source.1` The folder wins. **Enforced:** a change to a synced File is
   refused with `file_write_constrained` and exit code 3. The refusal covers
   `penumbra files replace`, `penumbra files trash`, edits and a move to
   another folder. The folder owns the File's name and path. A rename in the
   same folder (`penumbra files move`) is not refused. It sets the File's title
   (card [file](https://docs.pnbr.io/concepts/file.md), rule [file.12](https://docs.pnbr.io/concepts/file.md#rule-file-12)). The name and path stay the folder's, so a
   note's `[[link]]` to the File still resolves. **Your job:** change the
   document in its folder and sync again, or stop syncing (rule [source.9](https://docs.pnbr.io/concepts/source.md#rule-source-9)). Do not work around
   the refusal by uploading a copy: the project then holds two editions
   (problem [two-editions-two-files](https://docs.pnbr.io/troubleshooting/two-editions-two-files.md)).
2. `source.2` Syncing has three kinds, and each has its own start. **Your job:**
   for a folder or vault on this computer, run `penumbra sync <folder>`. For
   Granola, run `penumbra sources connect granola`, then
   `penumbra sources link granola --all` or `--folder <folder-id>`. A Google
   Drive folder can only be started in the App.
3. `source.3` Plan before you apply. **Your job:** run
   `penumbra sync <folder> --dry-run`. It prints what is new, changed, renamed
   and removed, what it skips, and a plan id. Show the person the removals.
   **Enforced when you ask:** `penumbra sync <folder> --plan <plan-id>` applies
   that plan, and refuses if the folder changed since.
4. `source.4` Some files are never sent. **Enforced:** a sync skips the Obsidian
   settings folder, `.git`, the `.penumbra` folder and other hidden files. It
   also skips symlinks that lead outside the folder, and unsafe names. The plan
   counts them under "skipped".
5. `source.5` The first sync ties the folder to a collection, and later syncs send
   only what changed. **Your job:** name the collection with
   `--collection "<name>"`. Without it, Penumbra uses or makes one named after
   the folder.
6. `source.6` A large removal needs a decision. **Enforced:** a sync that removes
   every file, or over half of the files when that is more than 25, is refused.
   The code is `removal_review_required`, the exit code is 3, and nothing is
   sent.
   **Your job:** read the list with `--dry-run`, ask the person, and only then
   run again with `--allow-removals`.
7. `source.7` A removal goes to Trash and can be restored. **Enforced:** a
   deleted document leaves the collection as a File in Trash, not as a purge.
   Penumbra removes nothing from a list it could not read completely. A
   Google Drive folder that Penumbra can no longer read keeps its Files, marked
   as possibly out of date.
8. `source.8` A run is done when its status says so. **Your job:** run
   `penumbra sources status <source>`. Tell the person the folder is current
   only when the latest run succeeded and the status says "Up to date" and
   "All searchable". Penumbra cannot see a folder on a computer between
   syncs, so its status says "Last synced" with the time instead. Tell the
   person that time, never that the folder is current.
   `penumbra sync <folder>` brings in changes made since.
   `penumbra sources changes <source>` lists what the run
   added, changed, renamed, removed and skipped.
9. `source.9` Stopping and pausing differ. **Enforced:** `penumbra sources pause`
   stops new content and keeps the Files read-only, and `penumbra sync` of a
   paused folder is refused with `source_paused`. `penumbra sources disconnect`
   ends syncing for good, asks to confirm, and releases the Files as ordinary
   editable Files. Without a terminal it needs `--yes`, or it exits with
   `confirmation_required` and changes nothing. **Your job:** tell the person
   that changes in the folder stop arriving.
10. `source.10` Syncing the same folder again picks up where it ended.
    **Enforced:** `penumbra sync <folder>` after a stop uses the folder's earlier
    collection and matches a File at the same path with the one already there.
    Files added in Penumbra while syncing was off stay as they are.
11. `source.11` Synced folders belong to a person. **Enforced:** a key or a
    connected agent that runs `penumbra sources list`, `penumbra sync` or any
    other synced-folder command is refused with `human_session_required`. Members read synced
    folders. Owners and admins change them.
12. `source.12` Access can be lost. **Your job:** when `penumbra sources status`
    shows a Drive folder or a Granola key that no longer works, tell the person.
    Nothing was deleted. For Drive, the person reconnects in the App under
    **Synced folders**: open the folder and choose **Reconnect Google Drive**. For
    Granola, run `penumbra sources connect granola`, then
    `penumbra sources reconnect <source>`.
13. `source.13` A Granola key is a secret. **Enforced:** the command
    `penumbra sources connect granola` has no argument for the key. It asks with
    nothing shown on screen, or reads it from stdin with `--key-stdin`.
    **Your job:** never ask the person to paste a key into the chat.

## Failure signs

* A File refuses a change and says it is kept in sync with its folder: rule
  [source.1](https://docs.pnbr.io/concepts/source.md#rule-source-1).
* A sync exits with `removal_review_required`: rule [source.6](https://docs.pnbr.io/concepts/source.md#rule-source-6).
* A sync exits with `source_paused`: rule [source.9](https://docs.pnbr.io/concepts/source.md#rule-source-9).
* Search shows the old text after the folder changed: the last run is not done
  (rule [source.8](https://docs.pnbr.io/concepts/source.md#rule-source-8)). Or a new File is not ready yet (problem
  [new-file-not-searchable-yet](https://docs.pnbr.io/troubleshooting/new-file-not-searchable-yet.md)).
* Two copies of one document: problem [two-editions-two-files](https://docs.pnbr.io/troubleshooting/two-editions-two-files.md).

## Doors

| Door | Call |
| - | - |
| CLI | `penumbra sync`, `penumbra sources list`, `penumbra sources status`, `penumbra sources changes`, `penumbra sources runs`, `penumbra sources items`, `penumbra sources link`, `penumbra sources sync`, `penumbra sources pause`, `penumbra sources resume`, `penumbra sources disconnect`, `penumbra sources reconnect`, `penumbra sources connect granola`, `penumbra sources link granola` |
| MCP | none. No tool starts or manages a synced folder. Use the CLI. |
| SDK | `sources` |

`penumbra sources sync <source>` starts a run of a Google Drive or Granola
folder now. A folder on a computer syncs only with `penumbra sync <folder>`.
The person connects Google Drive in the App under **Synced folders**, and
chooses **Connect Google Drive**.

## The CLI word

The CLI calls a synced folder a source. This is not the source of a citation
or the source date (card [passage](https://docs.pnbr.io/concepts/passage.md), card [file](https://docs.pnbr.io/concepts/file.md)).

## HTTP reference

* [Create upload session](https://docs.pnbr.io/api/http-uploads-create.md)
* [Get upload session](https://docs.pnbr.io/api/http-uploads-get.md)
* [Add file](https://docs.pnbr.io/api/http-files-admit.md)
* [List files](https://docs.pnbr.io/api/http-files-list.md)
* [Resolve files](https://docs.pnbr.io/api/http-files-resolve.md)
* [Replace file](https://docs.pnbr.io/api/http-files-replace.md)
* [List file versions](https://docs.pnbr.io/api/http-versions-list.md)
* [Get file version](https://docs.pnbr.io/api/http-versions-get.md)
* [Get file processing status](https://docs.pnbr.io/api/http-files-processing.md)
* [Download file](https://docs.pnbr.io/api/http-files-download.md)
* [Get file text](https://docs.pnbr.io/api/http-files-text.md)
* [Get file pages](https://docs.pnbr.io/api/http-files-pages.md)
* [List file citations](https://docs.pnbr.io/api/http-files-citations.md)
* [Set file title](https://docs.pnbr.io/api/http-files-title.md)
* [Set file description](https://docs.pnbr.io/api/http-files-describe.md)
* [Set file tags](https://docs.pnbr.io/api/http-files-tags.md)
* [Set file source date](https://docs.pnbr.io/api/http-files-source-date.md)
* [Trash files](https://docs.pnbr.io/api/http-files-trash.md)
* [Restore files](https://docs.pnbr.io/api/http-files-restore.md)
* [Get file operation](https://docs.pnbr.io/api/http-operations-get.md)
* [Recover file request](https://docs.pnbr.io/api/http-requests-get.md)

## Keep going

[Collection](https://docs.pnbr.io/concepts/collection.md) · [File](https://docs.pnbr.io/concepts/file.md) · [Bring a set of documents into the project](https://docs.pnbr.io/guides/bring-in-a-corpus.md) · [Bring in a new edition of a document](https://docs.pnbr.io/guides/new-edition.md) · [A new edition is a separate File](https://docs.pnbr.io/troubleshooting/two-editions-two-files.md) · [Identical bytes make no new version](https://docs.pnbr.io/troubleshooting/same-bytes-no-new-version.md) · [A File has no source date](https://docs.pnbr.io/troubleshooting/file-has-no-source-date.md)

Penumbra Grammar 0.6.26


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.