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 already writes outputs when the run completes — so pull is only useful when you didn't (or couldn't) wait synchronously:

• Closed the terminal mid-translation. Reopen, run lingo pull — picks up wherever the run left off.
• Pulling from a different machine. Translator runs push on their laptop; CI / a teammate runs pull on the same checkout, same engine, same credentials, and gets the outputs.
• 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 run state at ~/.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 run_a8c...: wrote 12 file(s), 4 already in sync.

Dry run:

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

Run not yet complete:

Run run_a8c... is running, not pulling yet.

(pull doesn't block on running runs — re-run later, or use push next time, which waits.)

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.