Folder Documentation

# 1. Export your key once
export FOLDER_API_KEY=fmd_live_your_api_key

# 2. List your folders
curl https://folder.md/api/v1/folders \
  -H "Authorization: Bearer $FOLDER_API_KEY"

# 3. Start the MCP server for Claude Code, Codex, Cursor, or any MCP-compatible agent
FOLDER_API_KEY=$FOLDER_API_KEY npx @foldermd/mcp

# 1. Set your key
export FOLDER_API_KEY=fmd_live_your_api_key

# 2. Pick a Folder id from the dashboard or API
export FOLDER_ID=your_folder_id

# 3. Upload a tiny test file
echo "folder smoke test $(date -u +%Y-%m-%dT%H:%M:%SZ)" > /tmp/folder-smoke.txt

curl -X POST https://folder.md/api/v1/folders/$FOLDER_ID/files \
  -H "Authorization: Bearer $FOLDER_API_KEY" \
  -F "file=@/tmp/folder-smoke.txt" \
  -F "path=smoke/folder-smoke.txt"

# 4. Confirm it appears
curl https://folder.md/api/v1/folders/$FOLDER_ID/files \
  -H "Authorization: Bearer $FOLDER_API_KEY"

# Authenticate (prompts for your API key)
folder login

# Or pass the key directly
folder login --key fmd_live_your_api_key_here

# Check auth status
folder whoami

# Sign out
folder logout

# List all folders (shortcut: folder ls)
folder folders list

# Create a new folder
folder folders create my-project

# View folder tree
folder folders tree <folder-id>

# Delete a folder
folder folders delete <folder-id>

# Skip confirmation prompt
folder folders delete <folder-id> --force

# List files in a folder
folder files list <folder-id>

# Upload a file
folder files upload <folder-id> ./local-file.md

# Upload to a specific remote path
folder files upload <folder-id> ./doc.md --path docs/readme.md

# Upload a directory recursively
folder files upload <folder-id> ./src --recursive

# Download a file
folder files download <folder-id> <file-id> -o ./local.md

# Print file contents to stdout
folder files cat <folder-id> <file-id>

# Delete a file
folder files delete <folder-id> <file-id>

# One-time sync of ./my-project to a folder
folder sync <folder-id> ./my-project

# Watch mode: sync continuously as files change
folder sync <folder-id> ./my-project --watch

# Also delete remote files that no longer exist locally
folder sync <folder-id> ./my-project --watch --delete

# Preview what would be synced (no changes made)
folder sync <folder-id> ./my-project --dry-run

# Ignore additional patterns
folder sync <folder-id> ./my-project --ignore "*.log" "dist/**"

# Analyze a file (actions: describe, summarize, extract, suggest-tags, detect-language)
folder ai analyze <folder-id> <file-id> --action describe
folder ai analyze <folder-id> <file-id> --action summarize
folder ai analyze <folder-id> <file-id> --action suggest-tags

# Get folder organization suggestions (actions: organize, rename, cleanup, structure)
folder ai suggest <folder-id> --action organize
folder ai suggest <folder-id> --action structure

# Run directly (no install needed)
FOLDER_API_KEY=fmd_live_... npx @foldermd/mcp

# Or install globally
npm install -g @foldermd/mcp
FOLDER_API_KEY=fmd_live_... foldermd-mcp

{
  "mcpServers": {
    "folder": {
      "command": "npx",
      "args": ["-y", "@foldermd/mcp"],
      "env": {
        "FOLDER_API_KEY": "fmd_live_your_api_key"
      }
    }
  }
}

{
  "mcpServers": {
    "folder": {
      "command": "npx",
      "args": ["-y", "@foldermd/mcp"],
      "env": {
        "FOLDER_API_KEY": "fmd_live_your_api_key"
      }
    }
  }
}

{
  "mcpServers": {
    "folder": {
      "command": "npx",
      "args": ["-y", "@foldermd/mcp"],
      "env": { "FOLDER_API_KEY": "fmd_live_your_api_key" }
    }
  }
}

{
  "servers": {
    "folder": {
      "command": "npx",
      "args": ["-y", "@foldermd/mcp"],
      "env": { "FOLDER_API_KEY": "fmd_live_your_api_key" }
    }
  }
}

Authorization: Bearer YOUR_API_KEY

POST /api/v1/folders/{id}/keys
{
  "name": "my-agent-key",
  "permissions": ["read", "write"]
}

# List all folders
GET /api/v1/folders

# Create a folder
POST /api/v1/folders
{ "name": "my-folder" }

# Get folder details
GET /api/v1/folders/{id}

# Delete a folder
DELETE /api/v1/folders/{id}

# Get folder tree
GET /api/v1/folders/{id}/tree

# Create subfolder
POST /api/v1/folders/{id}/subfolders
{ "path": "docs/guides" }

# List files
GET /api/v1/folders/{id}/files

# Upload file (multipart)
POST /api/v1/folders/{id}/files
Content-Type: multipart/form-data
file: <binary>
path: optional/path/file.md

# Get file metadata
GET /api/v1/folders/{id}/files/{fileId}

# Download file
GET /api/v1/folders/{id}/files/{fileId}?download=true

# Delete file
DELETE /api/v1/folders/{id}/files/{fileId}

# Analyze a file
POST /api/v1/ai/analyze
{
  "folderId": "folder-id",
  "fileId": "file-id",
  "action": "describe" | "summarize" | "extract" | "suggest-tags"
}

# Get folder suggestions
POST /api/v1/ai/suggest
{
  "folderId": "folder-id",
  "action": "organize" | "rename" | "cleanup" | "structure"
}

import { FolderMD } from '@foldermd/sdk'

const client = new FolderMD({
  apiKey: process.env.FOLDER_API_KEY!,
})

// Create a folder
const { folder } = await client.folders.create({ name: 'my-project' })

// Upload text content
await client.files.upload(folder.id, {
  path: 'docs/readme.md',
  content: '# Hello World',
})

// Upload a File/Blob (e.g. in Node.js or browser)
await client.files.upload(folder.id, {
  path: 'logo.png',
  file: new Blob([buffer], { type: 'image/png' }),
})

// List files
const { files } = await client.files.list(folder.id)

// Download as text
const text = await client.files.downloadText(folder.id, files[0].id)

// Watch for changes via webhook
await client.watch(folder.id, 'https://my-agent.example.com/webhook')

from foldermd import FolderClient

client = FolderClient(api_key="your-api-key")

# Create a folder
folder = client.folders.create(name="my-project")

# Upload a file
client.files.upload(
    folder_id=folder.id,
    path="docs/readme.md",
    content="# Hello World"
)

# List files
files = client.files.list(folder.id)

# AI analysis
analysis = client.ai.analyze(
    folder_id=folder.id,
    file_id=file_id,
    action="summarize"
)