← Back to Help Center

1. 1. Get a token

   Create a repo:write personal access token and export it as COLLAB_TOKEN (or pass --token).

2. 2. Set the server URL

   Export COLLAB_URL to your Collaborate instance (defaults to http://localhost:3035 for local dev).

3. 3. Pull a repository

   First-time Windows setup: on the repo page click Get a local copy and run get-{repo}.cmd. Pick an empty folder and paste your PAT in the popup. That downloads the branch tip and writes .collab/state.json. The CLI equivalent is collab pull owner/repo [branch] --dir ./my-copy. Download ZIP is a file snapshot only and cannot push later.

4. 4. Check sync status

   Run collab status --dir ./my-copy to see whether your local tip matches the remote tip and whether you have unpushed file changes. Exit code 2 means you are behind and should pull before pushing.

5. 5. Connecting a brand-new, still-empty repository

   A repository with zero commits has nothing to download, so collab pull returns a 404. Run collab init owner/repo [branch] --dir ./my-project instead — it writes .collab/state.json without contacting the server, tracking the folder against that branch. From an empty repository page, the Show me how card gives you a ready-to-paste prompt for this.

6. 6. Push changes

   Edit files locally, then collab push owner/repo [branch] -m "Your message" --dir ./my-copy. Push fails with exit code 1 if the remote branch moved — run collab status, then collab pull, reconcile, and push again. After collab init, the first push becomes that branch's root commit.

7. 7. Team path

   Prefer a feature branch + pull request into the default branch. Protect main when multiple developers share a repo. See Sync vs deploy.

8. 8. Help output

   Run collab --help to see the full usage summary for pull, push, and status flags.