Recover access to your workspace

Getting a new device into your workspace depends on what you still have. If you have at least one Authorized Device, adding another only takes an approval. If you've lost every Authorized Device, your Recovery Key is how you grant a fresh device decryption access. This guide walks through both, then shows how to verify access and rotate your key afterward.

Before you start

You need Bowline installed on the new device and the ability to sign into your account. Beyond that, you need one of two things.

• An existing Authorized Device you can run commands on, or
• Your Recovery Key words, generated earlier with bowline recover create.

Signing in proves your identity, but it doesn't release workspace decryption keys on its own. One of the two above must create the grant.

If you still have an Authorized Device

Approve the new device from one you already trust.

1. On the new device, run bowline setup --root ~/Code. It authenticates your account and creates a Device Approval Request with a short matching code.
2. On an Authorized Device, run bowline status --root ~/Code to see the pending request, including the device name, request age, and matching code.
3. Confirm the matching code is identical on both devices.
4. Run bowline device approve --root ~/Code --code <matching-code> to approve the matching request, or bowline device approve --root ~/Code --request <id> for a specific one. Add --yes to skip the prompt.
5. Verify access with bowline status --root ~/Code on the new device.

For more detail on this path, see Device trust.

If you have lost every Authorized Device

When no Authorized Device is available, use your Recovery Key to grant the new device access.

1. On the new device, install Bowline and run bowline setup --root ~/Code. This authenticates your account and creates a pending Device Approval Request. Account sign-in alone does not release decryption keys.

2. Find your Recovery Key id with bowline recover status. Use --json if you're scripting.

3. Grant this device access by giving your Recovery Key words to bowline recover use <id> on stdin. It reads the words from stdin rather than from arguments, so they never land in your shell history:

   printf '%s' "$RECOVERY_WORDS" | bowline recover use <id>

   Never write your Recovery Key words to a file. They are the highest-value secret in Bowline, and a file on disk outlives the moment you needed it.

   Bowline decrypts the recovery envelope locally, creates the pending request, publishes a self-addressed encrypted grant, accepts it, and stores the workspace key locally. The device is now an Authorized Device.

Verify access

Confirm the new device is trusted before you rely on it. Run bowline status --root ~/Code on the new device and check that it reports an Authorized Device and a healthy status. Your projects under ~/Code now materialize ordinary files in the background like any other trusted device.

Rotate your Recovery Key afterward

Recovering with a Recovery Key means the words left their storage and passed through a command. We recommend rotating the key after every recovery so the exposed words can't be reused.

1. Run bowline recover rotate to generate a fresh Recovery Key and invalidate the previous envelope.
2. Store the new words somewhere safe and offline.
3. Optionally revoke the old key explicitly with bowline recover revoke <id>.

Clean up lost devices

If you recovered because devices were lost or stolen, remove their access once you're back in. Run bowline device revoke --root ~/Code --device <id> for each lost device. A revoked device loses workspace decryption authority immediately and can no longer create work views, so it can't read your workspace if it resurfaces.

Next steps

• Recovery keys: what a Recovery Key is and the full bowline recover reference.
• Device trust: how approval and decryption access work.
• Add a machine: bring a new device into your workspace.
• CLI commands: full reference for bowline recover, approve, and revoke.