# Agent Versioning and Publishing in Codebuff: A Complete Technical Guide

> Automate agent versioning and publishing in Codebuff using the CLI. Discover how the publish command increments versions and uploads definitions to the registry.

- Repository: [Codebuff/codebuff](https://github.com/CodebuffAI/codebuff)
- Tags: deep-dive
- Published: 2026-03-09

---

**Agent versioning and publishing in Codebuff is fully automated through the CLI `publish` command, which increments semantic versions automatically and uploads agent definitions to the registry via the `/api/v1/agents/publish` endpoint.**

Codebuff provides a streamlined workflow for agent versioning and publishing that treats agents as version-controlled components living in the `.agents` directory. This article examines the complete technical process—from the `AgentDefinition` schema to the server-side validation logic that governs how agents are published and versioned in the Codebuff ecosystem.

## Understanding the Agent Versioning Model

### The AgentDefinition Interface

Every agent in Codebuff is defined by the `AgentDefinition` interface located in [`agents/types/agent-definition.ts`](https://github.com/CodebuffAI/codebuff/blob/main/agents/types/agent-definition.ts). This TypeScript declaration establishes the contract for agent metadata, including the optional `version` field.

The interface defines `version` as an optional string. When omitted, Codebuff assumes a default value of **`0.0.1`**. This design choice allows developers to publish agents without manually managing version numbers, as the framework handles automatic incrementing during the publish lifecycle.

### Automatic Version Incrementing

The logic responsible for calculating the next version number resides in [`cli/scripts/release.ts`](https://github.com/CodebuffAI/codebuff/blob/main/cli/scripts/release.ts). When a publish operation succeeds, this script implements a **patch-level bump** (incrementing the third digit in semantic versioning format). This ensures that each subsequent publish operation produces a monotonically increasing version string (e.g., `0.0.1` → `0.0.2` → `0.0.3`) without requiring manual edits to the source definition.

## The Publishing Pipeline

### CLI Command Execution and Local Processing

The entry point for publishing is implemented in [`cli/src/commands/publish.ts`](https://github.com/CodebuffAI/codebuff/blob/main/cli/src/commands/publish.ts) through the `handlePublish` function. When a developer executes `codebuff publish <agent-id>`, the CLI performs several preparatory steps before contacting the server:

1. **Load Definitions**: The command invokes `loadAgentDefinitions` to scan the `.agents` directory and parse all TypeScript definition files.
2. **Match Agents**: It identifies the target agents by matching against either the `id` field or the `displayName` property.
3. **Template Processing**: For agents utilizing generator-based steps, the CLI converts `handleSteps` functions into serialized strings suitable for transmission.
4. **Dependency Collection**: The system gathers a complete list of **all local agent IDs** to support server-side validation of `spawnableAgents` references.

After processing, the CLI constructs the payload and transmits it via `apiClient.publish`.

### API Request Schema and Server Validation

The network contract between CLI and backend is strictly defined in [`common/types/api/agents/publish.ts`](https://github.com/CodebuffAI/codebuff/blob/main/common/types/api/agents/publish.ts). The request body sent to `POST /api/v1/agents/publish` contains two critical components:

- An **array of raw agent definitions** (the complete agent objects after template processing)
- A comprehensive list of **local agent IDs** used for dependency resolution

On the server side, the route handler in [`web/src/api/agents/publish/route.ts`](https://github.com/CodebuffAI/codebuff/blob/main/web/src/api/agents/publish/route.ts) executes the validation and storage logic. This endpoint verifies that the `publisher` field exists and that the authenticated user has appropriate access rights. It then resolves any local dependencies referenced in `spawnableAgents` and, upon successful validation, **assigns the new version number** by incrementing the previously stored version for that specific publisher and agent ID combination.

The server response includes the `publisherId` and an array of published agent metadata (`{ id, version, displayName }`), which the CLI formats into a human-readable success message.

## Practical Implementation Examples

### Defining an Agent with Optional Versioning

```typescript
// agents/definitions/my-agent.ts
import { AgentDefinition } from '../../agents/types/agent-definition';

export const definition: AgentDefinition = {
  id: 'quick-summarizer',
  displayName: 'Quick Summarizer',
  publisher: 'my-organization',  // Required for publishing
  model: 'anthropic/claude-opus-4.6',
  instructionsPrompt: 'Summarize the user\'s text in ≤ 2 sentences.',
  // version field omitted - will default to 0.0.1 and auto-increment
};

```

### Publishing via CLI Command

```bash

# Publish a single agent

$ codebuff publish quick-summarizer
✅ Published: my-organization/quick-summarizer@0.0.2

# Publish multiple agents simultaneously

$ codebuff publish agent-one agent-two agent-three
✅ Published 3 agents under publisher: my-organization

```

### Programmatic Publishing

```typescript
import { handlePublish } from '../cli/src/commands/publish';

async function deployAgents() {
  const result = await handlePublish(['quick-summarizer']);
  
  if (result.success) {
    console.log(`Publisher: ${result.publisherId}`);
    result.agents?.forEach(agent => {
      console.log(`✅ ${agent.id}@${agent.version} published successfully`);
    });
  } else {
    console.error('Publish failed:', result.error);
    if (result.hint) console.info('Hint:', result.hint);
  }
}

```

## Summary

- **Version defaults are automatic**: If omitted in [`agents/types/agent-definition.ts`](https://github.com/CodebuffAI/codebuff/blob/main/agents/types/agent-definition.ts), the version defaults to `0.0.1` and increments via [`cli/scripts/release.ts`](https://github.com/CodebuffAI/codebuff/blob/main/cli/scripts/release.ts) on each publish.
- **Publisher authentication is mandatory**: The `publisher` field must be present in the agent definition, and the CLI validates access rights before transmission.
- **Dependency resolution is server-side**: The [`web/src/api/agents/publish/route.ts`](https://github.com/CodebuffAI/codebuff/blob/main/web/src/api/agents/publish/route.ts) endpoint validates all `spawnableAgents` references against the list of local agent IDs provided in the request body.
- **Atomic multi-agent publishing**: The `handlePublish` function in [`cli/src/commands/publish.ts`](https://github.com/CodebuffAI/codebuff/blob/main/cli/src/commands/publish.ts) supports publishing multiple agents in a single operation, with the API returning distinct version numbers for each.
- **Template serialization occurs client-side**: Handlebars-style generators in `handleSteps` are converted to strings before transmission to [`common/types/api/agents/publish.ts`](https://github.com/CodebuffAI/codebuff/blob/main/common/types/api/agents/publish.ts) endpoints.

## Frequently Asked Questions

### What happens if I omit the version field in my agent definition?

Codebuff automatically assigns version `0.0.1` as specified in [`agents/types/agent-definition.ts`](https://github.com/CodebuffAI/codebuff/blob/main/agents/types/agent-definition.ts). During the publish workflow, [`cli/scripts/release.ts`](https://github.com/CodebuffAI/codebuff/blob/main/cli/scripts/release.ts) calculates the next patch version, ensuring the registry receives an incremented version (e.g., `0.0.2`) without requiring manual file edits.

### How does Codebuff validate agent dependencies during publishing?

The CLI collects all local agent IDs and includes them in the request payload defined in [`common/types/api/agents/publish.ts`](https://github.com/CodebuffAI/codebuff/blob/main/common/types/api/agents/publish.ts). The server route [`web/src/api/agents/publish/route.ts`](https://github.com/CodebuffAI/codebuff/blob/main/web/src/api/agents/publish/route.ts) cross-references these IDs against any agents listed in the `spawnableAgents` array, ensuring all dependencies are either already published or available in the current publish batch.

### Can I publish multiple agents in a single command?

Yes. The `handlePublish` function in [`cli/src/commands/publish.ts`](https://github.com/CodebuffAI/codebuff/blob/main/cli/src/commands/publish.ts) accepts an array of agent identifiers. It processes each definition sequentially, bundles them into a single API request to `/api/v1/agents/publish`, and returns a consolidated result containing version numbers for all successfully published agents.

### Where does the version bump logic execute?

The version increment logic resides in [`cli/scripts/release.ts`](https://github.com/CodebuffAI/codebuff/blob/main/cli/scripts/release.ts). This module determines the next semantic version by reading the current registry state and calculating the appropriate patch increment before the CLI displays the final version string to the developer.