Versioning

Every `cableknit push` stores a copy of the bundle on the server. You can view your version history and roll back to any previous version if a push introduces a problem.

## How it works

- Each push creates a version record tied to the bundle's semver from `plugin.json`
- The server stores the last **10 versions** per plugin — older versions are automatically pruned
- Rollback re-ingests the stored bundle zip, so the plugin returns to exactly the state it was in at that version
- Rollback **re-validates** the bundle against current platform rules — if validation rules have tightened since the original push, the rollback may fail
- Rollback **preserves approval status** — a live plugin stays live after rollback (it does not reset to draft)

## View version history

```bash
cableknit versions <plugin-slug>
```

Displays a table with VERSION, PUSHED AT, and NOTES columns.

### Flags

| Flag | Description |
|------|-------------|
| `--json` | Output structured JSON |

### Example

```bash
cableknit versions my-plugin
```

```
VERSION       PUSHED AT             NOTES
1.2.0         2026-03-24 14:00:00   Added Slack integration
1.1.0         2026-03-23 14:00:00   Bug fixes
1.0.0         2026-03-21 14:00:00   Initial release
```

## Roll back

```bash
# Interactive — pick from a version list
cableknit rollback <plugin-slug>

# Direct — specify the version
cableknit rollback <plugin-slug> --version 1.1.0
```

In interactive mode, the CLI shows your version history as a picker. Select a version and confirm to execute the rollback.

### Flags

| Flag | Description |
|------|-------------|
| `--version` | Version to roll back to (required in non-interactive mode) |
| `--json` | Output structured JSON |

### What happens during rollback

1. The server downloads the stored bundle zip for the target version
2. The bundle is re-validated against current platform rules
3. If valid, the bundle is re-ingested — the plugin's skills, automations, blueprints, tools, and docs are replaced with the contents of that version
4. A `bundle_rollback` log event is recorded with `from_version` and `to_version` metadata

### Push notes

You can attach notes to each push to make version history more useful:

```bash
cableknit push --notes "Added Slack integration"
```

Notes appear in the version history and help you identify which version to roll back to.

## Retention

The platform retains the **10 most recent versions** per plugin. Older versions and their stored bundles are automatically pruned on each push. If you need to roll back further than 10 versions, you'll need to push from your local copy.

## Interactive shell

Both commands are available in the interactive TUI shell under the **Monitor** section. Launch with:

```bash
cableknit
```

Every cableknit push stores a copy of the bundle on the server. You can view your version history and roll back to any previous version if a push introduces a problem.

How it works

Each push creates a version record tied to the bundle’s semver from plugin.json
The server stores the last 10 versions per plugin — older versions are automatically pruned
Rollback re-ingests the stored bundle zip, so the plugin returns to exactly the state it was in at that version
Rollback re-validates the bundle against current platform rules — if validation rules have tightened since the original push, the rollback may fail
Rollback preserves approval status — a live plugin stays live after rollback (it does not reset to draft)

View version history

cableknit versions <plugin-slug>

Displays a table with VERSION, PUSHED AT, and NOTES columns.

Flags

Flag	Description
`--json`	Output structured JSON

Example

cableknit versions my-plugin

VERSION       PUSHED AT             NOTES
2.0         2026-03-24 14:00:00   Added Slack integration
1.0         2026-03-23 14:00:00   Bug fixes
0.0         2026-03-21 14:00:00   Initial release

Roll back

# Interactive — pick from a version list
cableknit rollback <plugin-slug>

# Direct — specify the version
cableknit rollback <plugin-slug> --version 1.1.0

In interactive mode, the CLI shows your version history as a picker. Select a version and confirm to execute the rollback.

Flags

Flag	Description
`--version`	Version to roll back to (required in non-interactive mode)
`--json`	Output structured JSON

What happens during rollback

The server downloads the stored bundle zip for the target version
The bundle is re-validated against current platform rules
If valid, the bundle is re-ingested — the plugin’s skills, automations, blueprints, tools, and docs are replaced with the contents of that version
A bundle_rollback log event is recorded with from_version and to_version metadata

Push notes

You can attach notes to each push to make version history more useful:

cableknit push --notes "Added Slack integration"

Notes appear in the version history and help you identify which version to roll back to.

Retention

The platform retains the 10 most recent versions per plugin. Older versions and their stored bundles are automatically pruned on each push. If you need to roll back further than 10 versions, you’ll need to push from your local copy.

Interactive shell

Both commands are available in the interactive TUI shell under the Monitor section. Launch with:

cableknit