> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: Project & workspace commands
description: Reference for scaffolding, linking, listing, and inspecting AGNT5 projects, and for switching the active workspace.
category: CLI
last_verified: 2026-07-24
---

The **`agnt5 create`**/**`agnt5 init`** pair sets up a project directory and links it to AGNT5. **`agnt5 projects`** and **`agnt5 info`** look up existing projects. **`agnt5 workspace`** switches the default workspace new projects and deployments resolve into.


**Commands**: `agnt5 create [name]`, `agnt5 init [name]` (alias `link`), `agnt5 info [project-id]`, `agnt5 projects`, `agnt5 workspace list`, `agnt5 workspace use <name>` (alias `ws`)
**Required**: authenticated session (`agnt5 auth login`) unless `--local`/`--new` is skipped
**Key flags**: `--template`, `--project`, `--workspace`, `--new`, `--language`
**Side effects**: `create`/`init` write project files and a `.agnt5/project-ref` binding; `workspace use` updates the default workspace stored in `~/.agnt5/config.yaml`


## Command summary

| Command | Purpose |
| --- | --- |
| `create [name]` | Scaffold a new project in a **new** directory and register it on AGNT5. |
| `init [name]` | Set up the **current** directory as an AGNT5 project (scaffold, add config, or relink). |
| `info [project-id]` | Show information about a project. |
| `projects` | List projects visible to your account. |
| `workspace list` | List available workspaces. |
| `workspace use <name>` | Set the default workspace. |

## `agnt5 create`

```bash
agnt5 create [name] [options]
```

Convenience wrapper around `agnt5 init`: it makes a new directory, scaffolds a starter project into it, and links it to AGNT5. To set up the current directory instead, use `agnt5 init`.

| Flag | Description |
| --- | --- |
| `--template <name>` | Template to scaffold from, e.g. `python/weather-agent`, optionally pinned with `@version`. |
| `--version <version>` | Template version. Default: latest. |
| `--local` | Create the project locally without registering it on AGNT5. |
| `--verbose`, `-v` | Show verbose output including download details. |
| `--dry-run` | Show what would be created without executing. |

```bash
agnt5 create my-agent
agnt5 create my-agent --template python/weather-agent
agnt5 create my-agent --template python/weather-agent@v1.0.0 --local
```

## `agnt5 init`

```bash
agnt5 init [name] [options]
```

Alias: **`agnt5 link`**. Sets up the **current directory** as an AGNT5 project. Behavior depends on what's already there:

- **Empty directory** — scaffolds a starter project and links it.
- **Existing code** — adds a minimal `agnt5.yaml` and links it, without touching your files.
- **Already an AGNT5 project** — relinks or updates the existing binding.

| Flag | Description |
| --- | --- |
| `--project <id\|ref>` | Link to an existing project instead of scaffolding. |
| `--workspace <id\|name>` | Workspace to link within; skips the workspace prompt. |
| `--new` | Create a new empty project on AGNT5 and link to it. Mutually exclusive with `--project`. |
| `--name <name>` | Project name, used with `--new` as an alternative to the positional argument. |
| `--language <lang>` | Language for scaffolding or a new project. Default: from `agnt5.yaml`, or `python`. |
| `--template <name>` | Template to scaffold from. |
| `--version <version>` | Template version. Default: latest. |
| `--verbose`, `-v` | Show verbose output. |
| `--dry-run` | Show what would be initialized without executing. |

```bash
agnt5 init my-agent                        # Scaffold + link the current directory
agnt5 init                                 # Set up + link the current directory
agnt5 init --project <project-id>          # Link to an existing project by ID
agnt5 init --new --name my-proj            # Create a new project and link to it
agnt5 init my-agent --template python/weather-agent
```

## `agnt5 info`

```bash
agnt5 info [project-id] [options]
```

Shows project information. Resolves the target in order: the positional `project-id`, then `--ref`, then the project linked to the current directory.

| Flag | Description |
| --- | --- |
| `--ref <ref>` | Project reference name. |

```bash
agnt5 info                      # Info for the project linked in this directory
agnt5 info proj_9f2a
agnt5 info --ref acme/my-agent
```

## `agnt5 projects`

```bash
agnt5 projects [options]
```

Lists all projects visible to your account.

| Flag | Description |
| --- | --- |
| `--page <n>`, `-p` | Page number. Default: `1`. |
| `--page-size <n>` | Projects per page. Default: `20`. |
| `--search <text>`, `-s` | Search in project name, ref, or slug. |
| `--language <lang>`, `-l` | Filter by language. |
| `--status <status>` | Filter by status. |
| `--order-by <field>` | `created`, `updated`, or `name`. Default: `updated`. |
| `--order-dir <dir>` | `asc` or `desc`. Default: `desc`. |

```bash
agnt5 projects
agnt5 projects --search weather --language python
agnt5 projects --order-by created --order-dir asc --page-size 50
```

## `agnt5 workspace`

```bash
agnt5 workspace <command>
```

Alias: **`agnt5 ws`**. Manages and switches the active workspace — the default target for new projects and deployments.

- **`agnt5 workspace list`** — Lists available workspaces. No flags. The current default is marked with `*`.
- **`agnt5 workspace use <name>`** — Sets the default workspace by name or ID. Resolves by case-insensitive name match first, then exact ID; errors if a name matches more than one workspace.

```bash
agnt5 workspace list
agnt5 workspace use acme-prod
agnt5 ws use ws_7c1e
```

## Local project files

Project-aware commands rely on two files created by `create`/`init`:

| File | Purpose |
| --- | --- |
| `.agnt5/project-ref` | Binds the working directory to a project reference. Required by `deploy`, `run`, `logs`, `secrets`, and other project-scoped commands. |
| `agnt5.yaml` | Project manifest: language, deployment defaults, and build configuration. |

<Callout type="tip">
If you clone an existing project, make sure both files are present before running `agnt5 deploy` or `agnt5 dev` — otherwise re-link with `agnt5 init --project <id>`.
</Callout>

## Next steps

- [Deploy commands](/docs/cli/deploy.md): build and deploy the project you just created.
- [Local development](/docs/cli/dev.md): run your worker locally before deploying.
- [Auth commands](/docs/cli/auth.md): log in before creating or linking a project.
- [Configuration](/docs/cli/configuration.md): where `agnt5.yaml` and credentials live on disk.