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

# CLI Overview

> The Versuno CLI for managing AI assets, projects, and teams from your terminal.

The Versuno CLI is a developer-first tool for syncing AI assets between your local filesystem and the Versuno cloud. It follows a Git-style workflow: pull assets down, edit them, then push new versions back up.

## Requirements

* [Bun](https://bun.sh) ≥ 1.0

## Installation

```bash theme={null}
bun add -g versuno-cli
```

Or run without installing:

```bash theme={null}
bunx versuno-cli <command>
```

## Quick start

```bash theme={null}
versuno login                  # authenticate with your API key
versuno teams list             # list your teams
versuno switch <id>            # set the active workspace
versuno prompts init           # scaffold .versuno/ in your project
versuno prompts assets list    # browse assets in the active workspace
versuno prompts pull <id>      # pull an asset to disk
versuno prompts push -m "msg"  # push local changes as a new version
```

Prefer to stay private? Capture your coding agents' memory into a local store instead of the cloud, no account needed, then search it back:

```bash theme={null}
versuno memory capture --local              # aggregate agent memory to ~/.versuno/memory/
versuno memory recall "how to write PRs"    # keyword-search the local store
versuno memory install-hook                 # let Claude Code recall automatically
```

## Command groups

Commands are organized by domain. Auth and workspace commands stay at the top level; the prompt-manager (asset versioning) commands live under the `prompts` group, and memory capture/recall lives under `memory`.

| Group       | Commands                                                              | What it does                                                             |
| ----------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| *auth*      | `login`, `logout`                                                     | Authenticate and sign out                                                |
| *workspace* | `switch`, `teams`                                                     | Choose the active team                                                   |
| `memory`    | `capture`, `recall`, `install-hook`                                   | Capture coding-agent memory (cloud or local) and recall it               |
| `prompts`   | `init`, `push`, `pull`, `status`, `diff`, `log`, `assets`, `projects` | Sync and version prompt assets (projects scope which assets you work on) |

Run `versuno prompts --help` for the full prompt-manager command list, or `versuno <group> <command> --help` for any command's options.

## How it works

`versuno prompts init` creates a `.versuno/` directory in your project root:

```
.versuno/
  contexts/
  prompts/
  personas/
  system-prompts/
  skills/
  projects/
  .temp/          ← ephemeral state (gitignored)
  .gitignore
```

Each asset is stored as a Markdown file with YAML frontmatter:

```md theme={null}
---
id: abc123
type: prompt
title: My prompt
version: 3
tags: [customer-support]
created_at: 2026-01-01T00:00:00Z
updated_at: 2026-04-01T12:00:00Z
---

You are a helpful assistant...
```

The CLI tracks content hashes so only modified files are pushed or flagged as changed.

## Environment variables

| Variable            | Description                                              |
| ------------------- | -------------------------------------------------------- |
| `VERSUNO_API_KEY`   | API key. Overrides stored credentials.                   |
| `VERSUNO_WORKSPACE` | Active workspace ID. Overrides the stored workspace ref. |
| `VERSUNO_DEBUG`     | Set to any value to enable verbose error output          |