# Merkleshare CLI for AI Agents

This document provides a quick reference for AI agents to use the Merkleshare CLI to store and share files.

## Installation

```bash
curl -fsSL https://www.merkleshare.com/install.sh | bash
```

## Authentication

```bash
# Authenticate with Merkleshare (opens browser)
ms login

# Check current auth status
ms whoami

# Sign out
ms logout
```

## Commands

### Create collection with files

```bash
ms create "collection name" ./file1.txt ./file2.md --public
```

Options:
- `--public` - Make collection visible on profile
- `--unlisted` - Accessible via link only (default)
- `--private` - Only visible to owner

### Add files to existing collection

```bash
ms add <collection> ./file1.txt ./file2.md
```

### List collections

```bash
# Your collections
ms ls

# Another user's public collections
ms ls @username

# Files in a collection
ms ls <collection>
```

### Get Sia URL for a file

```bash
ms sia <collection> <filename>
```

Returns a portable Sia URL that can be imported into other Sia-compatible applications.

### Download files

```bash
ms download <collection>
ms download <collection> -o ./output-dir
```

### Share collection

```bash
ms share <collection>
```

### Search

```bash
ms search "query"
```

### Public feed

```bash
ms feed
```

## Collection identifiers

Collections can be referenced by:
- **Name**: The display name
- **ID**: Short ID from `ms ls` output
- **URL**: Full collection URL

Partial ID matching is supported.

## Output formats

Add `-f json` for JSON output:

```bash
ms ls -f json
ms create "name" -f json
```

## Example workflow

```bash
# Create a public collection and add files
ms create "Project Artifacts" ./report.pdf ./data.csv --public

# Get the share link
ms share "Project Artifacts"

# Get Sia URL for portable sharing
ms sia "Project Artifacts" report.pdf
```

## More information

- Docs: https://www.merkleshare.com/docs/cli
- CLI downloads: https://www.merkleshare.com/cli