fileroute

Fileroute records where project artifacts come from, where they live locally, and where they should be published. A YAML or JSON descriptor connects local files to SharePoint, Google Drive, and S3 locations. Preview transfers without credentials, visualize the relationships, pull remote inputs, and publish to supported targets through the CLI or Python API. Python 3.11+ is required.

Current transfer support: SharePoint, Google Drive, and S3 can be pulled; SharePoint and Google Drive can be pushed. S3 targets can be described and diagrammed, but push --dry-run rejects them until upload support exists. Fileroute does not transform files or transfer directly between cloud providers.

Descriptor format change

Catalogs and resources are now keyed maps: resources: {report: {path: report.csv}}. The map key is the registered name. Cross-file catalogs use catalogs: {archive: {descriptor: catalogs/archive.yaml}}. Run fileroute migrate OLD_DESCRIPTOR NEW_DIRECTORY --dry-run before converting existing named lists and $ref links. See the migration guide.

Get started

For a repeatable project workflow, add Fileroute as a dependency and commit the descriptor and uv.lock:

uv add fileroute
uv run fileroute diagram config/fileroute.yaml
uv run fileroute pull config/fileroute.yaml --dry-run

For occasional CLI use, run the published tool in a separate environment:

uvx fileroute diagram config/fileroute.yaml
uvx fileroute pull config/fileroute.yaml --dry-run

uv run uses the project's dependencies and supports Python imports; uvx does not install Fileroute into the project. Pin a version with uv add 'fileroute==X.Y.Z' or uvx --from 'fileroute==X.Y.Z' fileroute --help. See uv's project, dependency, and tool guides.

One supported workflow downloads a SharePoint file to a local artifact and publishes that artifact to two SharePoint destinations:

resources:
  monthly-report:
    path: artifacts/monthly-report.csv
    sources:
      - path: https://contoso.sharepoint.com/sites/data/Shared%20Documents/monthly-report.csv
    targets:
      - path: https://contoso.sharepoint.com/sites/reports/Shared%20Documents/monthly-report.csv
      - path: https://contoso.sharepoint.com/sites/archive/Shared%20Documents/monthly-report.csv

Save this as config/fileroute.yaml, replace the example URLs, and run:

uv run fileroute resolve config/fileroute.yaml
uv run fileroute diagram config/fileroute.yaml
uv run fileroute pull config/fileroute.yaml --dry-run
uv run fileroute pull config/fileroute.yaml
uv run fileroute push config/fileroute.yaml --dry-run
uv run fileroute push config/fileroute.yaml

resolve parses URLs and scoped paths offline; resolve --online --write verifies remote locations and saves their IDs and entity types. diagram and dry runs also work without provider access; --online and actual transfers require credentials. Configure credentials using .env-sample; see Authentication for provider setup.

To publish a new file to Google Drive, target an existing folder; Fileroute creates or replaces the file below it. An exact file URL instead replaces that file by ID and preserves its existing name:

resources:
  report:
    path: artifacts/report.csv
    targets:
      - path: https://drive.google.com/drive/folders/FOLDER_ID
      - path: https://drive.google.com/file/d/EXISTING_FILE_ID/view

The two targets receive separate copies. See Transfers for nested folders, shared drives, and ambiguous names.

Documentation

• Descriptor model, paths, references, and resolution
• More use cases, saved YAML, and generated diagrams
• Transfer behavior and provider support
• Diagram formats and Python graph API
• CLI reference and Python API
• Development, migration, and package releases

The descriptor path is a local artifact for transfers. sources are upstream inputs or provenance; targets are publication destinations. For nested edits, fileroute list shows exact JSONPath selectors; the leading $ is optional when passing one to list, update, or add --parent. Diagrams show intent, not a completed transfer. Use fileroute --help for commands and options. To develop this repository, run uv sync and see the contributor guide.

HTTP retries and upload recovery

Fileroute retries transient Microsoft Graph reads and content PUTs up to three times, respecting Retry-After when supplied. A content PUT reopens the local file on each attempt. Folder-creation POSTs are not automatically replayed after an uncertain result. Google Drive resumable uploads query the upload session after a transient or rate-limit error and continue from the byte offset confirmed by the server. Network and HTTP failures retain their provider-specific exception types and expose status_code, response_text, response_json, and response_headers for callers that need details.