---
name: projects
description: Projects in Anchorify — grouping shares inside an org.
---

# Projects

A **project** groups shares inside an org. Every share lives in exactly one project, and the project's slug is part of the share URL:

```
https://anchorify.io/<org>/<project>/<slug>
```

When you sign up, Anchorify creates a default project called `untitled` in your home org. Shares you publish without specifying a project land there.

## Why projects?

Projects exist because Anchorify is shared with non-technical clients, and per-share access toggles get unwieldy fast. With projects you can:

- Invite a client as a **viewer** of one project and keep the rest of your work invisible to them.
- Move a share between projects later (the URL redirects automatically — old links keep working).
- Rename a whole batch of share URLs by renaming the project slug, without re-publishing each share.

## Creating a project

Web: there's no UI for it yet — use the CLI or the API for now.

CLI:

```bash
anchorify project create q1-reports
anchorify project create q1-reports --name "Q1 Reports"
```

API:

```bash
curl -X POST https://anchorify.io/api/v1/orgs/<org-slug>/projects \
  -H "authorization: Bearer $REPO_SHARE_TOKEN" \
  -H "content-type: application/json" \
  -d '{"slug":"q1-reports","name":"Q1 Reports"}'
```

Slugs follow the same rules as share slugs: lowercase alphanumerics + hyphens, 1–60 chars. Reserved words (`settings`, `members`, `invite`, etc.) are blocked.

## Listing projects

```bash
anchorify project list           # human-readable
anchorify project list --json    # machine-readable
```

API: `GET /api/v1/orgs/<org-slug>/projects`. Org members see every project; project-only viewers see just the ones they're a member of.

## Renaming a project

Renaming a project slug writes a redirect so old share URLs in the project keep resolving (`/<org>/<old-slug>/<share> → /<org>/<new-slug>/<share>`).

```bash
anchorify project rename old-slug new-slug
```

The CLI prompts for type-to-confirm by default. Pass `--yes` to skip.

## Publishing into a multi-project org

When your org has 2+ projects, the publish endpoint requires a `--project` flag:

```bash
anchorify report.md --project q1-reports
```

If you forget it the CLI prints the list of available projects and the exact retry command, so you don't have to look anything up.

## Deleting a project

Three rules:

1. **Last-project block.** An org must keep at least one project. The CLI and API both refuse to delete the only project in an org.
2. **Empty project.** Deletes immediately.
3. **Project with shares.** You have to pick a strategy:
   - `delete`: remove the project and the shares with it. The CLI requires you to type-to-confirm the project slug, since this is destructive.
   - `move`: move the shares to another project in the same org first, then delete the now-empty project.

CLI (interactive):

```bash
anchorify project delete q1-reports
# CLI prompts for strategy + target if applicable.
```

CLI (scripted):

```bash
anchorify project delete q1-reports --strategy delete --yes
anchorify project delete q1-reports --strategy move --target q2-reports --yes
```

API: `DELETE /api/v1/orgs/<org-slug>/projects/<pslug>?strategy=delete` or `?strategy=move&target=<pslug>`.

## Sharing access (project viewers)

Adding viewers to a single project — without giving them admin access to the whole org — happens through invites. See [invites](/docs/invites). On a share page in your org, the chrome includes an **Invite** button for admins; the modal lets you pick "this project (viewer)" or "this org (admin)".