Git

Every Agentic Mode project has a git repository behind it. The wren CLI binds a local directory to that repository, and from then on ordinary git moves your modeling in and out — git push to upload, git pull to download.

Overview

Your project's models, views, relationships and knowledge are files. Wren AI keeps them in a git repository, so the same project can be edited in the web app and on your machine, and every change has an author and a history.

The CLI's job is only to connect the two. Once a directory is bound:

• git push uploads. Pushing modeling changes triggers a deploy, so the project picks them up.
• git pull downloads. Changes made in the web app arrive as commits.
• git log / git diff / branches work as they do anywhere else.

Nothing else routes through the CLI, and nothing about access depends on it.

How authentication works

Two credentials, with different lifetimes:

• A durable API key, stored locally and readable only by you. It never leaves your machine except to request the token below.
• A short-lived token, minted from that key on every git operation by a credential helper git runs itself. It is never written to disk.

So there is nothing long-lived in your git config or remote URLs, and an expired token is not something you can encounter — nothing holds one long enough.

Either key level works for the durable key, and which one you use is your choice:

• A project key grants access to that one project.
• An organization key works for any project in the organization, so one auth add per project still stores the same key — convenient, and broader than the project needs.

create is the exception: it requires an organization key, because the project does not exist yet and a project key could not be scoped to it. It then mints a project key for the new project and stores that — the organization key is used for the two API calls and never written to disk. So a project you created ends up holding the narrower credential without your having to make one.

The binding is the git remote

Nothing on your machine records which directory belongs to which project. The credential helper works it out from the repository path git gives it. That means git remote -v tells you the whole truth about what a directory is connected to, and removing the remote is a complete disconnect.

Before you start

1. Install the CLI.

   pip install wrenai

2. Create an API key in the web app — a project key under the project's API settings, or an organization key under the organization's.

3. Note your project id. It is in the project URL.

Download an existing project

Use this to get a project you already have in Wren AI onto your machine.

wren cloud auth add --project 1234
wren cloud link ./my-project

auth add stores the key and configures git; it asks for the key and touches no directory. link binds the directory and fetches the project's files into it.

From then on, use git:

cd my-project
git pull            # bring down changes made in the web app

link is safe to re-run if it fails partway. Once a directory is bound, git pull — not another link — is how you get updates.

Upload a project you built locally

Use this to take a Wren project you have on disk and make it a Wren AI project.

wren cloud create --org 42 --type BIG_QUERY --connection-info-file ./conn.json

This creates the project, connects its data source, binds the directory, and pushes — the push is what deploys your models.

The directory has to be a Wren project already (a wren_project.yml and models that compile). To start from nothing, create the project in the web app instead and download it as above.

--type and --connection-info are passed straight through to the API. For the accepted types and a connection example for each, see Create a project → Database connectionInfo examples.

Everything is checked before anything is created

If the directory is not a Wren project, its YAML does not compile, a data source is missing, or the directory is already bound, create refuses before making the project — so a mistake never leaves a half-configured project behind.

Afterwards, ordinary git:

git add models/
git commit -m "add the orders model"
git push            # deploys

Duplicate a project

To get a second project with the same modeling — a staging copy, a variant to experiment on, a per-customer fork — unbind the directory and create into it:

cd my-project
wren cloud unlink
wren cloud create --org 42 --type BIG_QUERY --connection-info-file ./conn.json

Your files never leave the directory. unlink only removes the remote, and create makes a new project whose starting content is what is already there, then pushes it — so the duplicate arrives with your models already deployed.

Points worth knowing:

• The original is untouched. It keeps its own repository, and nothing is pushed to it. Only the directory changed which project it points at.
• The duplicate inherits the git history, because it is the same directory. If you would rather the copy start clean, remove .git before create.
• The data source is a fresh choice. create takes --type and connection info, so the duplicate can point at the same source as the original or at a different one — a staging warehouse, for instance.
• The organization key is required, as for any create.

Why not link to an existing project instead?

link refuses to bind a directory whose history came from a different project, because that would merge two projects' content and publish the result on the next push. Duplicating goes through create precisely because the new project's repository is empty apart from its own initial commit, so there is nothing to collide with.

To move a directory to a different existing project, start from a clean directory and link that instead.

Day-to-day

You want to	Command
Get changes made in the web app	git pull
Publish your local modeling	git push
See what changed	git diff, git log
Check what a directory is connected to	git remote -v
See which credentials are stored	wren cloud auth list
Disconnect a directory	wren cloud unlink
Remove a stored key	wren cloud auth remove --project 1234

unlink removes the remote and nothing else — your key is kept, because another directory may still use it, and the project itself is untouched. Pass --forget-key to drop the key as well.

auth list prints what is stored, never the keys themselves:

PROJECT  API HOST (--host)         GIT HOST (git talks to)   REPO
1234     https://cloud.getwren.ai  https://cloud.getwren.ai  org/42/1234/shared-data.git

Both host columns are shown because they mean different things and, on a split-host deployment, differ. --host on the other commands is the API host — the one you gave auth add. Use this command rather than reading the credential file: that file is keyed by the git host, so it hands you the value --host will reject.

Self-hosted

Pass --host with your deployment's URL:

wren cloud auth add --project 1234 --host https://wren.example.com

If your deployment serves the API and the git repositories on different hosts, pass --git-host as well. On Wren AI Cloud you do not need either.

Troubleshooting

git asks for a username or password. The credential helper is not being found. It resolves wren from your PATH at the moment git runs, so a different or older wren first on PATH will not serve it. Run wren cloud auth add again — it refuses up front if the wren git would use cannot do the job.

git push says the upstream branch does not match. Your local branch and the project's default branch have different names. link aligns them; if you renamed the branch afterwards, rename it back or set the upstream explicitly.

A push succeeded but the project did not change. Deploys are triggered by modeling files. A commit that touches only unrelated files will not deploy anything.

Reference

Every flag, and the rest of the CLI, is in the CLI reference — see the wren cloud section.