Documentation

Getting Started

Storing is a cloud asset optimization service that automatically classifies, compresses, and converts your assets to optimal formats. It supports images, videos, PDFs, audio files, and SVGs. For images, a 3-tier classification system (icon, standard, hero) applies the right compression strategy, achieving typical savings of 40-70% without visible quality loss.

Three ways to use Storing

Quick start: compress a file in 30 seconds

npm install -g @supertype.ai/storing
storing login --email [email protected] --password yourpassword
storing compress hero-banner.png

That's it. Storing will classify the image, pick the optimal format (AVIF by default), and save the compressed file alongside the original. Requires authentication — sign up for free to get started.

CLI Reference

The storing CLI compresses images through Storing's optimization pipeline and manages remote bucket operations (including multi-asset optimization) via the Storing API. All operations require authentication.

Installation

npm install -g @supertype.ai/storing

Requires Node.js 18+. After installing, the storing command is available globally.

Authentication

An account is required for all operations. Sign up for free at use.storing.app.

# Create an account
storing register --email [email protected] --password yourpassword --name "Your Name"

# Log in (saves token to ~/.storing/credentials.json)
storing login --email [email protected] --password yourpassword

# Log out
storing logout

Compression

The compress command sends images to Storing's cloud optimization pipeline. Each image is classified into a tier (icon, standard, hero) and compressed with tier-appropriate quality settings. The compressed file is downloaded back to your machine automatically. Requires authentication.

# Compress a single file
storing compress image.png

# Specify output format
storing compress image.png --format avif
storing compress image.png --format webp
storing compress image.png --format jpeg

# Compression profiles
storing compress image.png --profile conservative  # higher quality
storing compress image.png --profile balanced       # default
storing compress image.png --profile aggressive     # smaller files

# Size-based compression
storing compress image.png --max-size 200KB
storing compress image.png --max-size 100KB --min-quality 70

# Compress a directory
storing compress ./images/ --recursive
storing compress ./images/ --recursive --format avif --output ./optimized/

# JSON output (for scripting)
storing compress image.png --json

Options

Bucket Operations

These commands interact with the Storing API and require authentication via storing login.

Connect a bucket

# Connect an S3 bucket (uses CloudFormation for IAM role)
storing connect s3://my-bucket --role-arn arn:aws:iam::123456:role/Storing-ReadOnly

# Connect a GCS bucket (opens OAuth in browser)
storing connect gs://my-bucket

For S3, running storing connect s3://my-bucket without a --role-arn prints a CloudFormation Quick Create link to set up the read-only IAM role.

Audit

# Audit a connected bucket
storing audit s3://my-bucket

# Audit a local directory
storing audit ./public/images

Audits scan all images, classify them, and project potential savings without modifying any files.

Optimize

# Optimize with defaults (balanced profile, auto format, images only)
storing optimize s3://my-bucket

# Optimize with specific settings
storing optimize s3://my-bucket --profile aggressive --format avif

# Multi-asset optimization — process specific asset types
storing optimize s3://my-bucket --types image,video,pdf
storing optimize s3://my-bucket --types video --video-codec h265 --video-resolution 1080p
storing optimize s3://my-bucket --types pdf --pdf-quality 80
storing optimize s3://my-bucket --types audio --audio-bitrate 128
storing optimize s3://my-bucket --types svg --svg-precision 3

Starts an optimization job on the server. The CLI polls for progress and shows a live progress bar with ETA. Use the --types flag to specify which asset types to process (defaults to images only). See Multi-Asset Support for details on per-type options.

Status & Apply

# Check all jobs
storing status

# Check a specific job
storing status <job-id>

# Apply optimized files (shows the aws s3 cp command)
storing apply <job-id>

# Preview without executing
storing apply <job-id> --dry-run

History

# View all past jobs
storing history

# Filter by bucket
storing history s3://my-bucket

Environment Variables

MCP Integration

Storing provides a Model Context Protocol (MCP) server that lets AI coding agents compress images, audit directories, and manage bucket optimizations through natural language. Works with Claude Code, Cursor, Windsurf, and any MCP-compatible client.

Setup

Add the MCP server to your project's .mcp.json or global Claude config:

{
  "mcpServers": {
    "storing": {
      "command": "npx",
      "args": ["-y", "@supertype.ai/storing-mcp"],
      "env": {
        "STORING_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

The MCP server requires an API key for authentication. Generate one from the Settings page and set it as the STORING_API_KEY environment variable. You can also use STORING_TOKEN with a JWT token from storing login.

Available Tools

storing_compress parameters

storing_audit parameters

Example AI Agent Interaction

Here's how a typical interaction works when an AI agent has the Storing MCP server configured:

Dashboard Guide

The web dashboard at use.storing.app provides a visual interface for all bucket operations.

Per-Bucket Optimization Settings

Each connected bucket can have its own default optimization settings. Configure these from the bucket detail page to avoid re-entering options every time you start a job. When you create an optimization job, the bucket's defaults are pre-filled automatically.

Settings are stored as part of the bucket configuration and can also be managed via the API:

# Get current bucket optimization defaults
curl -H "Authorization: Bearer <token>" \
  https://use.storing.app/api/buckets/:id/settings

# Update bucket optimization defaults
curl -X PATCH -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"format":"avif","profile":"aggressive","applyMode":"writeback"}' \
  https://use.storing.app/api/buckets/:id/settings

Write-Back Modes

Storing supports three modes for delivering optimized files, controlled by the applyMode setting:

Write-back and subfolder modes require additional permissions on the source bucket. For S3, deploy the write-back IAM role using the CloudFormation template:

# CloudFormation template for write-back IAM role
# Adds s3:PutObject and s3:DeleteObject to the Storing role
aws cloudformation create-stack \
  --stack-name Storing-WriteBack \
  --template-url https://storing-staging.s3.ap-southeast-1.amazonaws.com/templates/write-back-role.yaml \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameters ParameterKey=BucketName,ParameterValue=your-bucket-name

For GCS, you will be prompted to re-authenticate with write scope (full_control) when enabling write-back or subfolder mode.

Upload to Bucket

Upload images directly to a connected bucket through Storing. Files are automatically optimized using the bucket's configured defaults before being written to the bucket.

From the bucket detail page, use the drag-and-drop upload zone to upload files. You can also use the API directly:

# Upload and optimize a file to a connected bucket
curl -X POST -H "Authorization: Bearer <token>" \
  -F "[email protected]" \
  -F "destinationPath=images/hero/" \
  https://use.storing.app/api/buckets/:id/upload

The destinationPath parameter is optional — if omitted, the file is placed at the bucket root. The file is compressed using the bucket's default format, profile, and tier settings before upload.

Multi-Asset Support

Beyond images, Storing can optimize videos, PDFs, audio files, and SVGs in your cloud buckets. Multi-asset optimization is available through the optimize command (bucket operations) and the API's job system.

Supported Asset Types

Per-Type CLI Flags

When running storing optimize, use --types to select which asset types to process, and per-type flags to control optimization settings:

# Process everything in a bucket
storing optimize s3://my-bucket --types image,video,pdf,audio,svg

# Videos only — cap at 1080p with H.265 encoding
storing optimize s3://my-bucket --types video --video-codec h265 --video-resolution 1080p

# PDFs only — compress embedded images at quality 75
storing optimize s3://my-bucket --types pdf --pdf-quality 75

# Multiple types with shared profile
storing optimize s3://my-bucket --types image,svg --profile aggressive

Profiles by Asset Type

The compression profile (conservative, balanced, aggressive) applies across all asset types but affects each type differently:

The --types flag and per-type options are also available through the API when creating optimization jobs via POST /api/jobs using the assetTypes array parameter.

Classification System

Storing uses a 3-tier classification system to apply the right compression strategy for each asset. For images, classification is based on dimensions and file size. Videos and PDFs use analogous tiers based on resolution and page count respectively.

Video classification

PDF classification

Confidence scoring

Each classification includes a confidence score (0-100%). Images that fall near tier boundaries receive lower confidence scores. Low confidence files are flagged in audit reports so you can review and reclassify them if needed.

Reclassification

You can override automatic classifications using the storing_reclassify MCP tool or by setting up glob-based rules with storing_rules. For example, you might force all files under /icons/ to the icon tier regardless of dimensions.

Profile offsets

Compression profiles shift the SSIMULACRA2 target up or down from the base tier value:

Per-tier optimization defaults

Each tier has default resize dimensions and maximum file size targets that are applied automatically during compression. These defaults ensure images are appropriately sized for their role without manual configuration.

These defaults can be overridden per-bucket via the bucket optimization settings. Images smaller than the max width are not upscaled.

Output Formats

Video codecs

Audio codecs

PDF optimization

PDF optimization compresses embedded raster images within the PDF while preserving text, vector graphics, fonts, and document structure. The --pdf-quality flag controls the JPEG quality of re-compressed embedded images (1-100).

SVG optimization

SVG files are optimized by reducing path precision, removing metadata and editor artifacts, collapsing redundant groups, and minifying the markup. The --svg-precision flag controls how many decimal places are kept in path data (fewer = smaller files, but less precise curves).

Image format modes

When specifying the --format flag (CLI) or format parameter (MCP), you can use these modes:

Works with Any Cloud

Storing's compression works with images from any source — AWS S3, Google Cloud Storage, Azure Blob Storage, Cloudflare R2, DigitalOcean Spaces, Backblaze B2, or your local file system. Just download your images, compress with Storing, and re-upload.

For S3 and GCS, Storing offers a fully automated pipeline (connect → audit → optimize → deliver). For other providers, use the CLI or MCP with your existing tools:

Azure Blob Storage

# Download
az storage blob download-batch -d ./images -s my-container --account-name myaccount

# Compress
storing compress ./images/ -r --format avif

# Re-upload
az storage blob upload-batch -s ./images -d my-container --account-name myaccount --overwrite

Cloudflare R2

# Download (R2 is S3-compatible)
aws s3 sync s3://my-bucket ./images --endpoint-url https://<account-id>.r2.cloudflarestorage.com

# Compress
storing compress ./images/ -r --format webp --profile balanced

# Re-upload
aws s3 sync ./images s3://my-bucket --endpoint-url https://<account-id>.r2.cloudflarestorage.com

DigitalOcean Spaces

# Download (Spaces is S3-compatible)
aws s3 sync s3://my-space ./images --endpoint-url https://nyc3.digitaloceanspaces.com

# Compress
storing compress ./images/ -r --format avif

# Re-upload
aws s3 sync ./images s3://my-space --endpoint-url https://nyc3.digitaloceanspaces.com

Any provider with rclone

# rclone works with 40+ cloud providers
rclone sync remote:my-bucket ./images

# Compress
storing compress ./images/ -r

# Re-upload
rclone sync ./images remote:my-bucket

With AI agents (MCP)

AI coding agents with the Storing MCP server can automate this workflow for any cloud. Just ask:

The agent handles the download/compress/upload loop automatically using the appropriate cloud CLI + storing_compress.

Authentication

Storing supports two authentication methods. Choose based on your use case:

When to use API keys

Use API keys when you can't do an interactive login — MCP servers, CI/CD pipelines, cron jobs, or any script that runs unattended. API keys don't expire but can be deleted from the Settings page. Each key tracks its own usage count.

When to use JWT tokens

Use JWT tokens for interactive CLI sessions and the web dashboard. Tokens expire after 7 days. Run storing login to get a fresh token.

Generating an API key

# Option 1: Web dashboard
# Go to Settings → API Keys → Generate Key
# Copy the key immediately — it's only shown once

# Option 2: CLI
storing login --email [email protected] --password yourpass
# Then use the Settings page to generate an API key

# Use the key in MCP config, scripts, or CI/CD:
STORING_API_KEY=sk-your-key-here storing compress image.png

API Reference

The Storing API is a REST service running at https://use.storing.app. The CLI and MCP server are thin clients over this API.

Auth

Compression

The POST /api/jobs endpoint accepts an optional assetTypes array parameter (e.g. ["image", "video", "pdf"]) to specify which asset types to process in a bucket optimization job. Per-type settings (videoResolution, videoCodec, pdfQuality, audioBitrate, svgPrecision) are passed in the job's settings object.

Buckets & Jobs

Usage & Monitoring

All endpoints except /api/health, /api/auth/register, and /api/auth/login require authentication via Authorization: Bearer <token> or Authorization: ApiKey sk-....