7. Locking

Back to the spec index

• A CLI locks its own data before writing and releases on exit, including after a crash. The CLI decides when, how, and which locks it uses, for queries and for mutations. The rules below describe the locks it does take.
• Mechanism: an OS file lock on a lock file, with details written inside.
  • The lock lives in the CLI’s state folder (section 9), for example ~/.local/state/<cli>/data.lock.
  • The CLI takes an exclusive OS lock on that file. If the process crashes, the OS releases the lock, so a crash leaves no stale lock.
  • While it holds the lock, the CLI writes its PID, start time, and the command into the file, so a person or another CLI can see who holds it (this shows up in the locked error, data.details.heldBy). The details are information only. The OS lock is what counts.
• Waiting: wait for a short default time, then fail. An adopter fixes the default (for example 5 seconds). The wait rides out brief overlaps. After that the command fails with locked (exit 7, retryable: true, section 5).
  • -lock-timeout sets the wait in whole seconds. -lock-timeout 10 waits up to 10 seconds. -lock-timeout 0 fails at once.
  • It is not a sensitive parameter (3a), so config may set a default.
• Each command takes and releases its own lock.
• Crash-safe writes: write temp file, then atomic rename. Re-running resumes cleanly.