# Quickstart

> Sign up, create an organization and a repository, install the CLI, clone, edit, add, stitch, and see your change on weave.directory.
>
> Source: https://www.weave.directory/docs/quickstart

From a new account to your first weaved stitch, in about ten minutes. You need macOS or Linux (Windows: see [the installer page](https://weave-cli.com/docs/install)).

## 1. Create your account

1. Go to [weave.directory/signup](https://www.weave.directory/signup). Enter **Full Name**, **Email** and **Password** (at least 8 characters), tick the terms box and click **Sign Up**.
2. Open the email from Weave and click the link. On the **Verify your email** page click **Verify email**. You need a verified email to create organizations and access tokens.
3. [Sign in](https://www.weave.directory/login). The first time, pick the role that best describes you (Developer, Team Lead, Reviewer or Manager) and click **Select**.

> **Turn on two-factor authentication now** if you will own or administer a team organization: owners and admins of an organization need 2FA to administer it (personal organizations are exempt). Go to your avatar → **Settings** → **Account** → **Set up 2FA**, scan the QR code and enter the 6-digit code.

## 2. Create an organization

In the web UI: click **+** in the header → **Organization** (or go to [/orgs/new](https://www.weave.directory/orgs/new)). Enter an **Organization Name** and an **Organization URL** (`weave.directory/<slug>`), then click **Create Organization**.

Or with the API, using a personal access token with the `org:admin` scope (step 4 shows how to make one):

```bash
curl -s https://weave.directory/api/v1/orgs \
  -H "Authorization: Bearer $WEAVE_PAT" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme", "slug": "acme"}'
```

```json
{ "id": "clx…", "slug": "acme", "name": "Acme" }
```

The slug is lower-case letters, digits and hyphens. A taken slug answers `409 conflict`.

## 3. Create a repository

In the web UI: on your organization's page click **New Repository** (or **+** → **Repository**). Choose the **Owner**, a **Repository Name**, an optional description, what to **Initialize with** (Default (README), Empty, Next.js / React, Rust / CLI or Python) and the **Visibility**, then click **Create Repository**. You land on `weave.directory/<org>/<repo>`. The repository has two workstreams, `main` and `dev` (`dev`'s parent is `main`), and the template's files are the first stitch on `main`.

Or with the API (scope `org:admin`, and you must be a member of the organization):

```bash
curl -s https://weave.directory/api/v1/orgs/acme/repos \
  -H "Authorization: Bearer $WEAVE_PAT" \
  -H "Content-Type: application/json" \
  -d '{"name": "shop", "description": "Our web shop", "private": true}'
```

```json
{ "id": "cm3k…", "name": "shop", "org": "acme", "slug": "acme/shop", "private": true,
  "workstreams": ["main", "dev"], "warnings": [] }
```

- `id` is the **repository id**. The Weave server API (`/api/weave/{repoId}/…`) takes this id, not `org/name`.
- `workstreams` defaults to `["dev"]`; every listed workstream is created with `main` as its parent. Want `main ← preprod ← dev` instead? See [Workstreams](https://www.weave.directory/docs/workstreams#set-up-main-preprod-dev).
- `template` defaults to `"empty"` over the API.

## 4. Create a personal access token

Go to your avatar → **Settings** → **Access Tokens**. Under **Generate New Token** give it a **Name**, an **Expiration** (30, 60 or 90 days, or 1 year), the **Scopes** you need (`repo:read` and `repo:write` are ticked by default) and the **Repository access**, then click **Generate Token**. Copy it now — it is shown once. Personal access tokens start with `weave_`.

| Scope | Lets the token |
| --- | --- |
| `repo:read` | Read repositories |
| `repo:write` | Stitch and weave in repositories |
| `repo:admin` | Administer and delete repositories |
| `org:admin` | Administer organizations (create repositories, agents) |
| `tokens:write` | Issue and revoke tokens |

## 5. Install the CLI and sign in

```bash
curl -fsSL https://weave-cli.com/install.sh | sh
weave --version          # weave 0.4.0
weave login              # paste the token; it is checked and saved in ~/.weave/config.json
```

`echo "$WEAVE_PAT" | weave login` reads the token from stdin. In CI or an agent sandbox you can skip `weave login`: set `WEAVE_TOKEN` and `weave clone`, `add`, `stitch` and `sync` work without prompts.

## 6. Clone the repository

```bash
weave clone acme/shop
cd shop
weave status
```

`weave clone <org>/<repo> [dir] [--workstream main] [--server URL]` downloads the head of the workstream in one request, writes the files, verifies them against the head and sets up `.weave/` connected to `https://api.weave.directory`. `weave status` is clean straight away. With `--json` (values shortened):

```json
{ "repo": "acme/shop", "dir": "shop", "workstream": "main", "head": "4218fab7…", "files": 3,
  "bytes": 1840, "server": "https://api.weave.directory", "state_included": true, "warnings": [] }
```

Already have a folder with code? Run `weave init --server https://api.weave.directory` in it instead (name the repository first with `weave remote add origin acme/shop` if your account can reach several).

## 7. Edit, add and stitch

Work on `dev`, then promote to `main`:

```bash
weave checkout dev
```

Edit a file with your editor, for example add a function to `src/cart.ts`. Then:

```bash
weave status                 # your draft, and edits on disk not added yet
weave add                    # record the edits in your draft, by symbol
weave stitch -i "Add a cart total helper" -w "checkout shows the total before tax"
```

- `-i/--intent` (required) says what the change is for. `-w/--why` keeps the rationale with the change and drafts a **decision record** anchored to the symbols you changed; you confirm it (`-y` records it without asking).
- The weave check runs at once. When it passes, the stitch is **weaved** and the head of `dev` moves.
- If part of it touched a symbol someone else owns, that part goes to them as a suggestion and the rest weaves. `weave status` marks it `awaiting <owner>`.

`weave stitch --json` prints the outcome:

```json
{ "result": "weaved", "workstream": "dev", "stitch": "9c1e…", "head": "77ab…",
  "suggestions": [], "routed": [], "held_back": [], "warnings": [] }
```

## 8. Promote to main

```bash
weave timeline               # weaved stitches of dev, newest first, with their ids
weave promote 9c1e --to main # a prefix of the stitch id is enough
```

The stitch goes through `main`'s own weave check and keeps its author, intent and why. If it relies on earlier stitches that are not in `main` yet, Weave lists them and asks; `--with-deps` promotes them together.

## 9. See it on the website

Open `weave.directory/<org>/<repo>`:

- **Code** shows the files of the selected workstream (pick it with the workstream selector) and a **latest stitch** link.
- **Weaved** (`/<org>/<repo>/stitches`) lists the weaved stitches with author, intent and why, with **Promote to {parent}** and **Revert** actions.
- **Workstreams**, **Suggestions**, **Change requests** and **Log** show the rest.

You can also stitch from the browser: **New** → **New File**, or edit a file, fill in **What is this change for?** and click **Stitch**.

## Next steps

- Work with others: [claims, suggestions and clashes](https://www.weave.directory/docs/working-together).
- Set up `main ← preprod ← dev`: [Workstreams](https://www.weave.directory/docs/workstreams).
- Run AI agents on the repository: [For AI agents](https://www.weave.directory/docs/agents).
- Keep a terminal following the head: `weave watcher` renews your claims, keeps files on disk in step and prints messages for you.