Move a local repo to the cloud

You can run tasks on your own machine with no account. See Run a task on your own machine. Later you may want those tasks in a cloud workspace, where your team can see them. ch auth login handles that move. This page explains the choices and what each one does.

An offline repo is a git repository where you ran ch without an account, so its tasks live only on your machine.

Sign in from the repo

Run this from inside the repo:

ch auth login

ch login does the same thing. CodeHerder opens your browser to sign in. After sign-in succeeds, it asks:

This repo works offline. What should it become?

If the sign-in fails, CodeHerder asks nothing. You choose one of three answers.

Choice	What happens
Keep this repo local	Nothing moves. The repo keeps working offline.
Move this repo to the cloud	The repo’s tasks and history move to a cloud workspace. The local copy is retired.
Keep this repo in sync with a cloud workspace	The same move, but the local copy stays as a live mirror.

You can answer up front with --connect local, --connect cloud or --connect hybrid. Without a terminal, --connect is required. CodeHerder refuses before it opens the browser if you leave it off.

Keep this repo local

CodeHerder asks you to confirm. Without a terminal, pass --yes. It then adds a line to .codeherder.env that keeps the repo on your machine. It sends nothing to the cloud beyond the sign-in.

The command prints a git add and git commit line for that file. Commit it if you want every clone to agree. See Project defaults for the CLI for what the file holds.

Move this repo to the cloud

CodeHerder does these steps in order:

1. Picks a workspace. It uses --workspace if you pass it. Otherwise it uses the workspace named in .codeherder.env. Otherwise it looks for the one workspace that already holds this repo’s git URL. If none matches, you choose from a menu or create a new workspace. A group is refused, because a group never owns work.
2. Registers the repo in that workspace if it is missing. A checkout with no origin remote registers nothing.
3. Waits for running sessions to end. It prints “Waiting for N running session(s)…”. It never stops a session for you. Without a terminal, pass --wait to let it wait.
4. Freezes the local workspace, so no new work starts in it.
5. Compares your definitions with the cloud. Your workflows and stages may differ from the cloud’s copy. If so, CodeHerder shows each difference and asks “Which version stays?”.
6. Copies your history. Tasks, sessions and events arrive with their original ids and timestamps. This can take several batches.
7. Retires the local workspace. Its history now lives in the cloud.
8. Writes the address and workspace into .codeherder.env.
9. Offers to release the imported tasks. They arrive parked, so nothing starts by surprise. One confirm releases them all. Without a terminal, pass --yes. Otherwise release each one with ch task unblock <blockerId>.
10. Checks that the server answers.

CodeHerder never runs git for you. It prints a git add and git commit line for .codeherder.env. Commit it so every clone agrees.

ch auth login --connect cloud --workspace <workspaceRef> --wait

If the move stops partway

Run ch auth login again in the same repo. CodeHerder picks up where it stopped and adds no duplicates. ch auth status lists an unfinished move in a table headed PROMOTION.

You can still back out with --connect local, but only while none of your history has reached the cloud. After that, finish the move.

Keep this repo in sync

This choice does the same move, then keeps the local copy. The repo stays a live mirror of the cloud workspace instead of retiring. CodeHerder also adds a line to .codeherder.env that marks the repo as in sync.

• A definition file that matches the cloud’s copy is tracked from then on.
• A definition file that differs stays untouched. Settle it with ch sync show <op> and ch sync resolve <op>. See the next section.
• The mirror lives in the .codeherder folder. See A repository’s project folder.
• CodeHerder waits about a minute for the first mirror to finish. If the local runtime is not running, it tells you to run ch device-server --local.

ch auth status shows the repo’s mode. For a synced repo it shows when the mirror last finished, or not yet.

Work offline in a synced repo

In a synced repo, ch keeps working when the server is out of reach. Some changes wait in a queue and go out later:

• ch task create and ch task edit. You can edit the title, description, priority, due date and declared fields.
• ch task comment.
• ch wiki write.

Other changes never queue. A status move, a claim or an approval fails while you are offline. A flag with no offline base, such as --cap or --base-branch, is refused offline.

Only a connected run by a person queues changes. An agent session never does.

Command	What it does
ch sync push	Sends edited definition files and delivers every queued change.
ch sync status	Shows what is queued, in conflict or refused.
ch sync conflicts	Lists only the changes in conflict or refused.
ch sync show <op>	Shows both versions of one change, with a diff.
ch sync resolve <op> --take local	Sends your version again.
ch sync resolve <op> --take remote	Keeps the cloud’s version and saves yours to a draft file.
ch sync resolve <op> --from-file <file>	Sends a version you merged by hand.
ch sync discard <op>	Drops the change. It writes your text to a draft file first.

Use ch sync --help for the full list. ch sync push never runs git.

Join from a teammate’s clone

Suppose a teammate committed a .codeherder.env that marks the repo as in sync. When you run ch auth login in your clone, you join that workspace. On a terminal, CodeHerder asks first. Without one, pass --connect hybrid. It sends no records. If your clone has its own offline history, that history moves first.

If you cannot read the workspace the file names, CodeHerder refuses and asks you to contact a workspace admin. It never creates a second workspace.

If no workspace you can see holds the repo, you see “No workspace you can see holds …”. Ask your teammate to add you before you create one. A new workspace is a second copy.

Outside an offline repo

In a clone that is not offline, --connect cloud or --connect hybrid joins the clone to its workspace. It sends no records. --connect local does nothing.

A dev session with no task has no history to move. It stays on your machine.

Related guides

• Run a task on your own machine: working without an account
• Project defaults for the CLI: the .codeherder.env file
• A repository’s project folder: definitions and the mirror
• Credentials and profiles: other ways to sign in
• Quickstart: set up a team from scratch