Skip to main content

Storage Skill

This skill enables Claude Code to manage AIchor storage buckets on your behalf. Invoke it by describing what you want to do — e.g. "upload this directory to AIchor", "list my buckets", "download the outputs".

Installing

Skills are installed by placing them in your Claude Code skills directory

Add the following files to your ~/.claude/skills/ directory so that it looks like this

~/.claude/skills/
├── aichor-storage/
│  ├── SKILL.md
│  └── reference.md (detailed API docs - loaded when needed)
└── (other skills)

SKILL.md

---
name: aichor-storage
description: Use when the user wants to manage storage on AIchor — upload/download files, list bucket contents, copy between buckets, delete files or directories, create directories, or get bucket credentials for a project.
---

# AIchor Storage Management

Manage files and directories in AIchor project storage buckets using the `aichor storage cloud` commands.

## Prerequisites

Before using this skill, ensure:

1. **AIchor CLI is installed**: Check with `aichor --version`
2. **Authenticated**: Run `aichor projects list` to verify — re-auth if needed:
   ```bash
   aichor auth key --apikey $AICHOR_API_KEY
   ```
3. **Context is set** (or pass `--project-name` / `--engine-name` on each command):
   ```bash
   aichor context list
   aichor context set project $AICHOR_PROJECT_NAME
   aichor context set engine $AICHOR_ENGINE_NAME
   ```

## Path Convention (Critical)

The CLI assumes:
- **Directory paths end with a trailing slash**: `./path/to/dir/`
- **File paths do NOT end with a trailing slash**: `./path/to/file.txt`

Getting this wrong causes unexpected behaviour. Always confirm with the user whether a path is a file or directory.

## Safety Rules for Destructive Operations

**ALWAYS use `--dry-run` before deleting anything non-trivial.**

Before executing `rm` on a directory or on patterns with `--include`/`--exclude`:
1. Run with `--dry-run` first and show the user what would be deleted
2. Ask for explicit confirmation before running without `--dry-run`
3. Never pass `--force` without user approval

## Workflow

### 1. Discover Buckets

```bash
# List all buckets for the project
aichor storage cloud list --output json

# Get bucket credentials (access keys, endpoint, etc.)
aichor storage cloud storage-credentials --engine-name <ENGINE_NAME> --output json
```

Capture the `storage-id` values from the list output — required for all subsequent commands.

### 2. Browse Bucket Contents

```bash
# Tree view (default) — good for exploring structure
aichor storage cloud list-contents --storage-id <STORAGE_ID>

# Recursive tree
aichor storage cloud list-contents --storage-id <STORAGE_ID> -r

# Size view — shows file sizes
aichor storage cloud list-contents --storage-id <STORAGE_ID> -r --output size

# Simple list (one file per line) — good for scripting
aichor storage cloud list-contents --storage-id <STORAGE_ID> -r --output simple

# List only a specific subdirectory (depth 0 = direct children only)
aichor storage cloud list-contents --storage-id <STORAGE_ID> --path /mydir/ -r --max-depth 0

# Filter by pattern
aichor storage cloud list-contents --storage-id <STORAGE_ID> -r --include "*.csv"
aichor storage cloud list-contents --storage-id <STORAGE_ID> -r --exclude "*.tmp"
```

### 3. Upload

```bash
# Upload a directory
aichor storage cloud upload \
  --local-path ./mydir/ \
  --storage-id <STORAGE_ID> \
  --remote-path /mydir/

# Upload a single file
aichor storage cloud upload \
  --local-path ./file.txt \
  --storage-id <STORAGE_ID> \
  --remote-path /mydir/file.txt

# Upload with parallel workers (faster for many small files)
aichor storage cloud upload \
  --local-path ./mydir/ \
  --storage-id <STORAGE_ID> \
  --remote-path /mydir/ \
  --max-workers 4

# Overwrite existing files at destination
aichor storage cloud upload \
  --local-path ./mydir/ \
  --storage-id <STORAGE_ID> \
  --remote-path /mydir/ \
  --overwrite
```

### 4. Download

```bash
# Download a directory
aichor storage cloud download \
  --remote-path /mydir/ \
  --storage-id <STORAGE_ID> \
  --local-path ./mydir/

# Download a single file
aichor storage cloud download \
  --remote-path /mydir/file.txt \
  --storage-id <STORAGE_ID> \
  --local-path ./file.txt

# Download with parallel workers
aichor storage cloud download \
  --remote-path /mydir/ \
  --storage-id <STORAGE_ID> \
  --local-path ./mydir/ \
  --max-workers 4

# Overwrite existing local files
aichor storage cloud download \
  --remote-path /mydir/ \
  --storage-id <STORAGE_ID> \
  --local-path ./mydir/ \
  --overwrite
```

### 5. Copy Between Buckets

```bash
# Copy a directory from one bucket to another
aichor storage cloud cp \
  --src-storage-id <SRC_STORAGE_ID> \
  --src-path /source-dir/ \
  --dst-storage-id <DST_STORAGE_ID> \
  --dst-path /destination-dir/

# Copy a single file
aichor storage cloud cp \
  --src-storage-id <SRC_STORAGE_ID> \
  --src-path /mydir/file.txt \
  --dst-storage-id <DST_STORAGE_ID> \
  --dst-path /mydir/file.txt
```

### 6. Create Directories

```bash
aichor storage cloud mkdir \
  --storage-id <STORAGE_ID> \
  --path /new-directory/
```

### 7. Delete Files or Directories

Always run `--dry-run` first on anything non-trivial:

```bash
# Preview deletion
aichor storage cloud rm \
  --storage-id <STORAGE_ID> \
  --path /mydir/ \
  --dry-run

# Preview with filter
aichor storage cloud rm \
  --storage-id <STORAGE_ID> \
  --path /mydir/ \
  --include "*.tmp" \
  --dry-run

# Delete after confirming dry-run output with user
aichor storage cloud rm \
  --storage-id <STORAGE_ID> \
  --path /mydir/file.txt \
  --force

# Delete with parallel workers
aichor storage cloud rm \
  --storage-id <STORAGE_ID> \
  --path /mydir/ \
  --force \
  --max-workers 4
```

## CLI Quick Reference

| Command | Description |
|---------|-------------|
| `aichor storage cloud list` | List project buckets |
| `aichor storage cloud list-contents --storage-id ID` | Browse bucket (tree/size/simple, supports -r, --path, --include, --exclude, --max-depth) |
| `aichor storage cloud upload --storage-id ID --remote-path PATH` | Upload file or directory |
| `aichor storage cloud download --storage-id ID --remote-path PATH` | Download file or directory |
| `aichor storage cloud cp --src-storage-id ID --src-path P --dst-storage-id ID --dst-path P` | Copy between buckets |
| `aichor storage cloud mkdir --storage-id ID --path PATH` | Create directory |
| `aichor storage cloud rm --storage-id ID --path PATH --dry-run` | Preview deletion |
| `aichor storage cloud rm --storage-id ID --path PATH --force` | Delete file or directory |
| `aichor storage cloud storage-credentials --engine-name NAME` | Get bucket access credentials |

## Troubleshooting

| Issue | Fix |
|-------|-----|
| Auth expired / permission error | `aichor auth key --apikey $AICHOR_API_KEY` |
| "project not set" | `aichor context set project <NAME>` or pass `--project-name` |
| "engine not set" | `aichor context set engine <NAME>` or pass `--engine-name` |
| Upload/download is slow | Increase `--max-workers` (try 4–8) |
| File not found in bucket | Check path — directories need trailing slash |
| Unexpected files deleted | Always use `--dry-run` first; check `--include`/`--exclude` patterns |

reference.md

## Additional resources

- For complete AIchor CLI details, see [reference.md](https://docs.aichor.ai/category/aichor-cli)