---
name: knbox
description: Upload webpages, Markdown files, and images to KN Box through the `knbox` CLI and return public preview URLs. Use when an agent needs to publish generated files for preview or sharing.
---

# KN Box Skill

Use KN Box when you need to upload files for preview or sharing.

## Requirements

- Use the `knbox` CLI as the only upload mechanism.
- Prefer non-interactive auth with `KNBOX_TOKEN` when available.
- Default server is `https://box.beforeve.com`.
- Do not upload sensitive information.

## Verify Access

Before uploading, verify the CLI can reach KN Box:

```bash
knbox auth whoami --json
```

If this fails because the user is not logged in, ask the user to run:

```bash
knbox auth login
```

In a non-interactive environment, ask the user for a KN Box CLI token and set:

```bash
export KNBOX_TOKEN=knbox_xxx
```

The default server is already `https://box.beforeve.com`. Set `KNBOX_URL` only when the user explicitly wants a different KN Box server.

## Upload Files

Upload a file or directory:

```bash
knbox upload <file-or-dir> --json
```

Upload into a specific remote directory:

```bash
knbox upload <file-or-dir> --to /agent-output --json
```

Read the returned JSON:

- `data.entryUrl` is the best URL to show for a webpage directory.
- `data.uploaded[].url` contains individual file URLs.
- `summary` is a short human-readable result.
- `breadcrumbs` contains useful follow-up commands.

## Navigation

List files:

```bash
knbox ls [path] --json
```

Change the saved remote directory:

```bash
knbox cd <path>
```

Open a file or directory:

```bash
knbox open <path> --json
```

For a file, `open` returns the public URL. For a directory, it returns a directory listing.

## Conflict Handling

Uploads fail on conflicts by default.

Use `--rename` only when creating a distinct copy is acceptable:

```bash
knbox upload <path> --rename --json
```

Use `--overwrite` only when the user explicitly wants to replace existing files:

```bash
knbox upload <path> --overwrite --json
```

## Failure Handling

If `knbox` exits non-zero, read stderr and report the failure. Do not assume the file was uploaded.