Library backups with the CLI

tylor sync backs up your account’s My library packages and custom fonts to a Git repository. It writes ordinary files, commits changes, and pushes them using Git on your computer.

This is a separate workflow from browser saving and project Git integration. It does not back up your projects, unpublished package-source edits, project-specific package snapshots, comments, sharing settings, or credentials. Use snapshots and folder backups for saved documents.

Set up a backup repository

You need the Tylor CLI and an API key, plus local Git configured with a commit name/email and access to your destination repository. Git uses your local SSH keys or HTTPS credential helper; the browser’s Git connections settings do not configure this workflow.

1. Create a dedicated repository for the library backup. A private, empty repository is a suitable starting point.

2. Configure the CLI, replacing YOUR_ACCOUNT with your Git account:

   tylor sync init git@github.com:YOUR_ACCOUNT/tylor-packages.git --branch main

3. Check the configuration and local Git state:

   tylor sync status

With CLI 0.6.0+, each account gets a checkout at ~/.tylor/sync/<account-scope> (a stable server/user hash). Existing backup paths remain with the migrated login. To choose another location, pass --dir during initialization:

tylor sync init git@github.com:YOUR_ACCOUNT/tylor-packages.git --dir ~/Backups/tylor-library --branch main

Initialization tries to clone the requested branch, then the repository’s default branch. If cloning fails, it can initialize a local repository instead. A successful init message therefore does not prove that the remote is reachable; verify the first push. The saved branch reflects the checkout’s actual branch, which may differ from the requested default.

Understand config.json

With CLI 0.6.0+, tylor sync init saves sync.repo, sync.dir and sync.branch inside the selected account entry in ~/.config/tylor/config.json. Use the commands to configure it; you do not need to edit credentials or construct this JSON yourself.

tylor auth list
tylor --account company sync init git@github.com:YOUR_COMPANY/tylor-backup.git
tylor --account company sync status
tylor --account company sync
tylor --account personal sync init git@github.com:YOUR_ACCOUNT/tylor-backup.git
tylor --account personal sync status

Save each account with tylor login before initializing backups. repo is the supplied SSH or HTTPS Git URL, dir is the local checkout, and branch is the detected/configured branch. New settings store an absolute directory. A leading ~ in an older setting still works. The old top-level sync settings migrate with the original login, never with a newly added company account. Different accounts cannot share a backup directory. A local marker under .git also checks the account/server before export or restore; it is not pushed to Git.

The config contains credentials and is private (mode 600 on macOS/Linux). Do not copy it into Git or paste it into chat. Use --account to select another saved login; each entry retains its server URL. A conflicting TYLOR_API_KEY or TYLOR_API_URL is refused.

Push and restore use the checkout’s Git remote named origin. Editing sync.repo alone does not change that remote, and running init against an existing checkout does not replace its remote or switch branches. For a different destination, initialize a fresh, dedicated directory and check tylor sync status before pushing.

Export, commit, and push

Run either form:

tylor sync
# Equivalent:
tylor sync push

Each run fetches the current package and font libraries, rewrites the exported files, commits any changes, and pushes. The repository contains:

packages/<name>/<version>/…
fonts/<filename>
tylor-packages.json
tylor-fonts.json
README.md

Use a dedicated checkout: exports replace packages/, fonts/, both manifests, and the generated README.md. The CLI stages all changes in the checkout, so unrelated files can also enter the commit.

Removing a library item in Tylor removes it from the next export. Earlier committed exports remain in Git history. If nothing changed, no new commit is created, but the CLI still attempts to push any existing local commits.

A push does not pull remote changes first. If another computer changed the remote branch, Git can reject the push. Inspect and reconcile the checkout before retrying; do not force-push over the other backup. A failed push can leave a useful local commit that has not reached the remote yet.

There is no continuous watcher or built-in schedule. Run the command when you want a backup, or configure your own scheduler. A scheduled job needs access to the same CLI, API key, and Git credentials, and should not overlap another sync run on the same checkout.

Restore packages and fonts

On a new machine, configure the destination Tylor account and initialize a checkout of the backup repository first. Then run:

tylor sync restore

Restore requires a successful fast-forward pull, then imports the local checkout into the Tylor account selected by your API key. By default, it skips package versions with an existing name/version pair and fonts with an existing filename. To intentionally replace those matches:

tylor sync restore --overwrite

Upgrade before restoring an untrusted backup

Use CLI 0.7.2 or newer (npm install -g tylor-cli@latest). Older versions could follow links outside the checkout and upload unrelated local files. With 0.7.2, a failed pull stops restore; fix Git authentication, connectivity or branch conflicts and retry. There is no stale-local fallback.

The CLI validates both manifests and reads every listed file before uploading any item, including items that would be skipped. Unsafe or missing files stop the whole preflight with no uploads. Paths must stay inside the backup, package entrypoints must be listed text files, and manifests must use version 1. Symlinks, hardlinks, nonregular files, traversal, duplicate paths, case/Unicode aliases and Windows-reserved filenames are refused. A package-only or fonts-only backup may have just its corresponding manifest; malformed manifests are never silently ignored.

Limits are 4 MiB per manifest, 32 MiB per package file, 20 MiB per font, 10,000 listed files and 256 MiB of combined file bytes. Larger backups must be split into smaller dedicated repositories before restoring. Do not remove or replace a suspicious link without checking the repository’s history and intended content; ask its maintainer for an ordinary-file backup.

Export checks server-provided names and data before replacing the old backup. It writes private staging files, then replaces the managed paths. Ordinary replacement errors attempt to restore the previous tree. If an interrupted run leaves .tylor-library-stage-*, preserve it and recover the previous/new files before syncing again; another export stops so recovery data is not accidentally committed. This is not a crash-atomic transaction across the whole checkout.

Use a dedicated checkout under a trusted local directory. Do not run sync concurrently or allow other processes to change its files while it runs. Git configuration/hooks and the parent directory are trusted local configuration. Validation protects against malicious repository files; it is not a sandbox against another process running as your OS user. On Windows, file modes do not provide POSIX-style owner-only permissions.

After preflight, uploads still happen individually. A network, quota or server validation failure can leave earlier items imported; inspect the library before retrying with --overwrite.

Restore does not delete library items that are absent from the backup. It restores library packages, not their original editable source projects. After restoring, open a document that uses the packages and fonts and check its preview or PDF.

Follow activity and troubleshoot

Open API activity in Tylor while running a sync. The feed shows the API requests that fetch or import library items. Local Git commands and the remote Git push are not Tylor API calls; check terminal output for their result.

Symptom	What to check
“not configured”	Run tylor sync init in the same user environment that runs the CLI.
“sync dir … is not a git repo”	Check sync.dir; use init to create the intended checkout. A JSON entry alone does not clone the repository.
API authentication fails	Check the environment’s TYLOR_API_KEY, top-level apiKey, and TYLOR_API_URL. The environment key takes precedence.
Git authentication or commit fails	Check local Git credentials and commit identity. These are separate from the Tylor API key.
Push is rejected	Check the checkout’s branch and remote changes; preserve local commits while reconciling.
Restore reports skipped items	Existing package versions and font filenames are preserved unless you request --overwrite.
Restore reports an unsafe path, link, missing file or size limit	No items were uploaded during this failed preflight. Inspect the backup and obtain a valid ordinary-file version; do not bypass the checks.

Git backup URLs must contain no embedded password or token. Use HTTPS with a Git credential helper, or SSH (git@host:path or ssh://git@host/path). Replace old credential-bearing URLs in both the saved backup configuration and Git remote before using sync. Sync refuses pre-existing staged changes and stages only its owned package/font backup paths; unrelated files are left unstaged.