> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev.byterover.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Local vs Cloud

> What ByteRover CLI does offline, what requires a cloud account, and how to upgrade from local to team sync

ByteRover CLI runs entirely on your machine with no cloud account required. Cloud features layer on top — adding team sync, multi-machine access, and backup — without changing the core local workflow.

## Commands: local vs cloud

<Tabs>
  <Tab title="TUI slash commands">
    Commands available in the interactive REPL (`brv`):

    | Works locally (no auth)                             | Requires cloud auth                    |
    | --------------------------------------------------- | -------------------------------------- |
    | `/status` — show local project state                | `/login` — authenticate with ByteRover |
    | `/locations` — list registered projects             | `/logout` — clear authentication       |
    | `/curate` — add context to local knowledge tree     | `/vc push` — push commits to cloud     |
    | `/query` — query local context tree                 | `/vc pull` — pull commits from cloud   |
    | `/connectors` — manage agent connectors             | `/vc clone` — clone a remote space     |
    | `/hub` — browse and install skills & bundles        | `/vc fetch` — fetch remote refs        |
    | `/providers` — connect and switch LLM providers `*` |                                        |
    | `/model` — select a model `*`                       |                                        |
    | `/vc init` — initialize version control             |                                        |
    | `/vc config` — set commit author identity           |                                        |
    | `/vc add` — stage files                             |                                        |
    | `/vc commit` — save staged changes                  |                                        |
    | `/vc status` — show working tree status             |                                        |
    | `/vc diff` — show context tree changes              |                                        |
    | `/vc log` — show commit history                     |                                        |
    | `/vc branch` — manage branches                      |                                        |
    | `/vc checkout` — switch branches                    |                                        |
    | `/vc merge` — merge branches                        |                                        |
    | `/vc reset` — unstage files or undo commits         |                                        |
    | `/vc remote` — manage remote connection             |                                        |
    | `/new` — start a fresh session                      |                                        |
  </Tab>

  <Tab title="CLI commands">
    Standalone commands available from any terminal:

    | Works locally (no auth)                                 | Requires cloud auth                     |
    | ------------------------------------------------------- | --------------------------------------- |
    | `brv` — start interactive REPL                          | `brv login` — authenticate with API key |
    |                                                         | `brv logout` — clear cloud credentials  |
    | `brv status` — show CLI status and context tree         | `brv vc push` — push commits to cloud   |
    | `brv locations` — list registered projects              | `brv vc pull` — pull commits from cloud |
    | `brv query` — query context tree                        | `brv vc clone` — clone a remote space   |
    | `brv curate` — add context to knowledge tree            | `brv vc fetch` — fetch remote refs      |
    | `brv providers` / `list` / `connect` / `disconnect` `*` |                                         |
    | `brv model` / `list` / `switch` `*`                     |                                         |
    | `brv connectors` / `list` / `install`                   |                                         |
    | `brv hub` / `list` / `install`                          |                                         |
    | `brv vc init` — initialize version control              |                                         |
    | `brv vc config` — set commit author identity            |                                         |
    | `brv vc add` — stage files                              |                                         |
    | `brv vc commit` — save staged changes                   |                                         |
    | `brv vc status` — show working tree status              |                                         |
    | `brv vc diff` — show context tree changes               |                                         |
    | `brv vc log` — show commit history                      |                                         |
    | `brv vc branch` — manage branches                       |                                         |
    | `brv vc checkout` — switch branches                     |                                         |
    | `brv vc merge` — merge branches                         |                                         |
    | `brv vc reset` — unstage files or undo commits          |                                         |
    | `brv vc remote` — manage remote connection              |                                         |
    | `brv restart` — restart the daemon                      |                                         |
  </Tab>
</Tabs>

<Note>
  `*` Provider and model commands work locally for third-party providers. However, selecting or switching to the **ByteRover built-in** provider requires a logged-in ByteRover account (`/login` or `brv login`).
</Note>

## Upgrade from local to cloud

<Tabs>
  <Tab title="TUI">
    <Steps>
      <Step title="Authenticate">
        Run `/login` inside the REPL to authenticate via browser:

        ```
        /login
        ```
      </Step>

      <Step title="Add a remote">
        Point your space to a remote on ByteRover cloud:

        ```
        /vc remote add origin https://byterover.dev/<team>/<space>.git
        ```

        Find the URL on the space's page in the [ByteRover Dashboard](https://app.byterover.dev).
      </Step>

      <Step title="Push local context to cloud">
        Push your commits to the remote space. Use `-u` to set upstream tracking:

        ```
        /vc push -u origin main
        ```
      </Step>

      <Step title="Pull on other machines">
        On any machine where you're authenticated, clone the space:

        ```
        /vc clone https://byterover.dev/<team>/<space>.git
        ```

        After the initial clone, use `/vc pull` to sync subsequent changes from teammates.
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI">
    <Steps>
      <Step title="Authenticate">
        ```bash theme={null}
        # Default: opens your browser for OAuth
        brv login

        # CI / SSH / non-interactive: pass an API key from
        # https://app.byterover.dev/settings/keys
        brv login --api-key <your-api-key>
        ```
      </Step>

      <Step title="Add a remote">
        Point your space to a remote on ByteRover cloud:

        ```bash theme={null}
        brv vc remote add origin https://byterover.dev/<team>/<space>.git
        ```
      </Step>

      <Step title="Push local context to cloud">
        Push your commits to the remote space. Use `-u` to set upstream tracking:

        ```bash theme={null}
        brv vc push -u origin main
        ```
      </Step>

      <Step title="Pull on other machines">
        On any new machine where you're authenticated, clone the space:

        ```bash theme={null}
        brv vc clone https://byterover.dev/<team>/<space>.git
        ```

        After the initial clone, use `brv vc pull` to sync subsequent changes from teammates.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## When to use cloud

| Use case               | Why                                                                     |
| ---------------------- | ----------------------------------------------------------------------- |
| **Team collaboration** | Share a space with teammates — everyone queries the same knowledge base |
| **Multi-machine sync** | Push from your laptop, pull on a server or a new machine                |
| **Backup**             | Persist your context tree outside the local repo                        |

<Note>
  All local features — curate, query, version control, provider selection, hub, connectors — work without a cloud account and without an internet connection when using a third-party or local LLM provider. The ByteRover built-in provider requires a logged-in ByteRover account.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Team Context Sync" icon="users" href="/common-workflows/team-context-sync">
    Full walkthrough of the shared context workflow for teams
  </Card>

  <Card title="Local Context Tree" icon="folder-tree" href="/context-tree/local-space-structure">
    Understand the local knowledge store before pushing it to cloud
  </Card>

  <Card title="Git-Semantic VC" icon="git-branch" href="/git-semantic/overview">
    Full guide to branching, merging, and remote sync
  </Card>

  <Card title="CLI Reference" icon="book" href="/reference/cli-reference">
    Complete flag reference for all commands
  </Card>
</CardGroup>