lingo pull

Fetch the most recent push's outputs and write them to disk, with conflict detection against the lockfile.

lingo pull [--force] [--dry-run]

When to use it#

lingo push exits as soon as the run is submitted, so pull is how you collect its outputs. Run it after any push without --wait — and when a push with --wait didn't get to write:

• Closed the terminal mid-translation. Reopen, run lingo pull — picks up wherever the run left off.
• Later in the same CI job. One step runs lingo push, a later step on the same runner and checkout runs lingo pull and gets the outputs. Other machines get them once they're committed.
• Resumed work after the run finished but before push could write. Network blip, process killed — pull finishes the job.

How it finds the run#

pull reads ~/.lingo/runs/<hash>.json where <hash> is derived from the absolute project root path. The file records the last runId from push. Without it, pull errors:

Error: No saved run state for this project (looked for ~/.lingo/runs/<hash>.json) — run
       `lingo push` first so we know which run's outputs to pull.

This file is per-machine and lives outside the repo (see Configuration for details on why).

Conflict detection#

Before writing each target, pull compares:

• Hash of the local file on disk
• Hash recorded in .lingo/lock.json as the last-known-server version

If they match → no local edits, safe to overwrite. If they differ → local edits exist; pulling would discard them. pull aborts:

Error: 3 conflict(s) — rerun with --force

The lockfile is the single source of truth here — it tracks what the server last wrote, not the source content. Manual edits to translated files that you want to keep should be committed (so they survive pull) or pulled with --force (so they get overwritten).

Flags#

--force / -f#

Overwrite local target files that have diverged from the lockfile. Use after you've reviewed the conflicts and decided the server version is canonical (e.g. someone else pushed a glossary update that should take precedence).

Recommended workflow:

git status                          # stash or commit local edits first
git stash                           # if you want to keep them aside
lingo pull --force
git stash pop                       # re-apply your edits, resolve conflicts manually

--dry-run#

Show what pull would do without touching the filesystem:

lingo pull --dry-run

Outputs the count of files that would be written and how many are already in sync. Useful in CI for asserting nothing has drifted.

Output#

Success:

✓ Pulled run lrg_a8c...: wrote 12 file(s), 4 already in sync.

Dry run:

Dry run complete. 16 file(s) already in sync.

Run failed or cancelled:

Run lrg_a8c... is failed, not pulling yet.

(pull waits on a run that's still pending or running, with the same progress display as push --wait, then writes the outputs. A failed or cancelled run has nothing to pull — see Runs, state, and recovery.)

Edge cases#

• No prior push. Error as above. There's no concept of "pull translations that exist somewhere on the server" — pull always targets a specific run.
• Run state pointing at a deleted/expired run. The engine returns 404; pull reports it cleanly. Delete ~/.lingo/runs/<hash>.json and re-run push.
• Different engine in .lingo/config.json than the one the run was created on. Engine ID mismatch — the CLI errors with the IDs. Re-run push against the current engine.