Prompt Storage

Prompt Storage allows enterprises to automatically back up Cline conversation history to cloud storage (AWS S3 or Cloudflare R2). This provides a centralized repository for compliance, audit trails, and usage analysis while maintaining local storage as the primary source of truth.

Overview

Every Cline task conversation is stored locally in ~/.cline/data/tasks/<taskId>/api_conversation_history.json. When prompt storage is enabled, a background sync worker automatically uploads these conversation files to your configured S3 or R2 bucket.

Compliance Ready

Maintain conversation records for regulatory requirements and internal policies.

Audit Trail

Track AI interactions across your organization with timestamped conversation logs.

Usage Analysis

Analyze conversation patterns, token usage, and model performance at scale.

Disaster Recovery

Backup conversation history independent of local storage for business continuity.

How It Works

Local Storage First: All conversations are written to local disk immediately
Background Sync: A worker process queues conversation files for upload
Reliable Upload: Automatic retry logic with configurable batch sizes
Cloud Backup: Files are stored in your S3/R2 bucket with the same path structure

Storage Architecture

What Gets Stored

Prompt storage uploads the following files from each task:

File	Content	Purpose
`api_conversation_history.json`	Full conversation in Anthropic MessageParam format	Core conversation data for analysis
Task metadata	Task ID, timestamps, model info	Correlation and indexing

What’s NOT Stored

Prompt storage does not include:

❌ Workspace files not accessed by Cline
❌ API keys or secrets
❌ User credentials or authentication tokens

Conversation history includes all tool inputs and outputs. This means code written via write_to_file, file contents read via read_file, and command outputs are included in the uploaded data. Review your compliance and data classification requirements before enabling.

Storage Path Pattern

Files are uploaded to your bucket following this structure:

s3://your-bucket/tasks/{taskId}/api_conversation_history.json

This mirrors the local storage structure, making it easy to correlate local and cloud data.

Configuration

Prompt storage is configured through Remote Configuration in the enterpriseTelemetry.promptUploading section.

Schema

{
  "enterpriseTelemetry": {
    "promptUploading": {
      "enabled": true,
      "type": "s3_access_keys",
      "s3AccessSettings": {
        "bucket": "your-cline-prompts",
        "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
        "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
        "region": "us-east-1",
        "intervalMs": 30000,
        "maxRetries": 5,
        "batchSize": 10,
        "maxQueueSize": 1000,
        "maxFailedAgeMs": 604800000,
        "backfillEnabled": false
      }
    }
  }
}

Configuration Fields

Core Settings

Field	Type	Required	Description
`enabled`	boolean	Yes	Enable/disable prompt storage
`type`	string	Yes	Storage type: `"s3_access_keys"` or `"r2_access_keys"`

Access Settings (S3/R2)

Field	Type	Required	Description	Default
`bucket`	string	Yes	S3/R2 bucket name	-
`accessKeyId`	string	Yes	AWS/Cloudflare access key ID	-
`secretAccessKey`	string	Yes	AWS/Cloudflare secret access key	-
`region`	string	S3 only	AWS region (e.g., `us-east-1`)	-
`endpoint`	string	R2 only	Cloudflare R2 endpoint URL	-
`accountId`	string	R2 only	Cloudflare account ID	-

Sync Worker Settings

Field	Type	Description	Default
`intervalMs`	number	Milliseconds between sync attempts	30000 (30s)
`maxRetries`	number	Maximum retries before giving up	5
`batchSize`	number	Items to process per interval	10
`maxQueueSize`	number	Maximum queue size before eviction	1000
`maxFailedAgeMs`	number	Time before discarding failed items	604800000 (7 days)
`backfillEnabled`	boolean	Sync existing tasks on startup	false

Setup Guides

AWS S3
Cloudflare R2

AWS S3 Configuration

Create S3 Bucket

Create a dedicated S3 bucket for Cline conversation storage:

aws s3 mb s3://your-cline-prompts --region us-east-1

Enable versioning and encryption:

aws s3api put-bucket-versioning \
  --bucket your-cline-prompts \
  --versioning-configuration Status=Enabled

aws s3api put-bucket-encryption \
  --bucket your-cline-prompts \
  --server-side-encryption-configuration '{
    "Rules": [{
      "ApplyServerSideEncryptionByDefault": {
        "SSEAlgorithm": "AES256"
      }
    }]
  }'

Create IAM Policy

Create an IAM policy with minimal required permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:PutObjectAcl",
        "s3:GetObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::your-cline-prompts/*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket"
      ],
      "Resource": "arn:aws:s3:::your-cline-prompts"
    }
  ]
}

Save this as cline-prompt-storage-policy.json and create the policy:

aws iam create-policy \
  --policy-name ClinePromptStorage \
  --policy-document file://cline-prompt-storage-policy.json

Create IAM User

Create a dedicated IAM user and attach the policy:

aws iam create-user --user-name cline-prompt-uploader

aws iam attach-user-policy \
  --user-name cline-prompt-uploader \
  --policy-arn arn:aws:iam::YOUR_ACCOUNT_ID:policy/ClinePromptStorage

aws iam create-access-key --user-name cline-prompt-uploader

Save the AccessKeyId and SecretAccessKey from the output.

Configure in Cline Dashboard

In the Cline admin console at app.cline.bot:

Navigate to Settings → Enterprise Telemetry
Enable Prompt Uploading
Select S3 as the storage type
Enter your bucket name, access key ID, secret key, and region
Configure sync worker settings (or use defaults)
Save configuration

Test Connection

Use the “Test Connection” button in the admin console to verify:

Bucket access
Write permissions
Credential validity

A test file will be uploaded and deleted from your bucket.

Optional: Lifecycle Policies

Configure retention policies for cost management:

{
  "Rules": [
    {
      "Id": "ArchiveOldPrompts",
      "Status": "Enabled",
      "Transitions": [
        {
          "Days": 90,
          "StorageClass": "GLACIER"
        }
      ]
    },
    {
      "Id": "DeleteOldPrompts",
      "Status": "Enabled",
      "Expiration": {
        "Days": 2555
      }
    }
  ]
}

Cloudflare R2 Configuration

Create R2 Bucket

Log in to the Cloudflare Dashboard
Navigate to R2 in the sidebar
Click Create bucket
Name your bucket (e.g., cline-prompts)
Select a location close to your users
Click Create bucket

Generate API Token

In the R2 dashboard, click Manage R2 API Tokens
Click Create API token
Configure permissions:
- Token name: Cline Prompt Storage
- Permissions: Object Read & Write
- Bucket: Select your bucket or use All buckets
Click Create API Token
Save the Access Key ID and Secret Access Key
Note your Account ID (shown in the R2 overview)

Get R2 Endpoint

Your R2 endpoint follows this format:

https://<ACCOUNT_ID>.r2.cloudflarestorage.com

Find your account ID in the Cloudflare dashboard under R2 overview.

Configure in Cline Dashboard

In the Cline admin console at app.cline.bot:

Navigate to Settings → Enterprise Telemetry
Enable Prompt Uploading
Select R2 as the storage type
Enter:
- Bucket name
- Access key ID
- Secret access key
- Account ID
- Endpoint URL
Configure sync worker settings (or use defaults)
Save configuration

Test Connection

Use the “Test Connection” button to verify:

Bucket access with provided credentials
Write permissions
Endpoint connectivity

Cost Advantages

R2 offers significant cost advantages over S3:

No egress fees: Download data at no cost
Lower storage costs: ~ $0.015/GB vs S3's ~$ 0.023/GB
Global edge access: Fast access from anywhere

Sync Worker Behavior

The background sync worker manages the upload queue with these characteristics:

Queue Management

FIFO ordering: Files are uploaded in the order they were created
Automatic batching: Processes up to batchSize items per interval
Queue size limits: Evicts oldest items when maxQueueSize is exceeded
Retry logic: Failed uploads are retried up to maxRetries times

Failure Handling

When an upload fails:

Immediate retry: Item stays in queue for next sync interval
Exponential backoff: Retry attempts are spaced out
Maximum retries: After maxRetries attempts, item is marked as permanently failed
Age-based cleanup: Failed items older than maxFailedAgeMs are discarded
No data loss: Local files remain intact regardless of sync status

Backfill Mode

When backfillEnabled is set to true:

On first startup, scans all existing tasks in ~/.cline/data/tasks/
Queues conversation files that haven’t been uploaded
Useful for enabling prompt storage on an existing Cline deployment
Can generate significant upload volume — monitor queue size

Enable backfill carefully on large deployments. Consider starting with backfillEnabled: false and monitoring the steady-state queue before enabling backfill.

Monitoring & Observability

Integration with OpenTelemetry

While prompt storage operates independently, it integrates with Cline’s observability system:

Task lifecycle events: task.created, task.completed track when conversations are generated
Conversation events: task.conversation_turn, task.tokens provide usage metrics
Local monitoring: Sync worker status is logged but not yet exported as OTel events

See OpenTelemetry for configuring metrics export.

CloudWatch Monitoring (S3)

Monitor S3 upload activity with CloudWatch:

# View PutObject requests (uploads)
aws cloudwatch get-metric-statistics \
  --namespace AWS/S3 \
  --metric-name NumberOfObjects \
  --dimensions Name=BucketName,Value=your-cline-prompts \
  --start-time 2026-03-01T00:00:00Z \
  --end-time 2026-03-08T00:00:00Z \
  --period 3600 \
  --statistics Sum

R2 Analytics

Cloudflare R2 provides built-in analytics in the dashboard:

Request counts and rates
Storage usage over time
Bandwidth utilization
Error rates

Security & Compliance

Encryption

At Rest:

S3: Enable server-side encryption (SSE-S3 or SSE-KMS)
R2: Encryption enabled by default

In Transit:

All uploads use HTTPS/TLS
Credentials are never logged or exposed

Access Control

Recommended IAM policies:

Use dedicated IAM users/roles
Limit permissions to write-only if read access isn’t needed
Enable MFA for credential generation
Rotate access keys regularly

Bucket policies:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Deny",
      "Principal": "*",
      "Action": "s3:*",
      "Resource": [
        "arn:aws:s3:::your-cline-prompts/*",
        "arn:aws:s3:::your-cline-prompts"
      ],
      "Condition": {
        "Bool": {
          "aws:SecureTransport": "false"
        }
      }
    }
  ]
}

Audit Logging

S3 Server Access Logging:

aws s3api put-bucket-logging \
  --bucket your-cline-prompts \
  --bucket-logging-status '{
    "LoggingEnabled": {
      "TargetBucket": "your-log-bucket",
      "TargetPrefix": "cline-prompts-access/"
    }
  }'

CloudTrail for API Calls: Enable CloudTrail to track all S3 API operations on your bucket.

Data Retention

Implement retention policies based on your compliance requirements:

GDPR: Consider right to erasure
SOC 2: Maintain audit trails for required period
HIPAA: Ensure appropriate retention and disposal

Troubleshooting

Common Issues

Queue size growing continuously

Symptoms: maxQueueSize limit reached, oldest items being evictedCauses:

Upload rate slower than conversation creation rate
Network connectivity issues
Insufficient batch size or interval

Solutions:

Increase batchSize to process more items per interval
Decrease intervalMs to sync more frequently
Check network connectivity and credentials
Temporarily increase maxQueueSize while investigating

Uploads failing with 403 Forbidden

Symptoms: Repeated upload failures, items reaching maxRetriesCauses:

Invalid or expired credentials
Insufficient IAM permissions
Bucket policy denying access

Solutions:

Verify credentials are correct in remote config
Check IAM policy includes s3:PutObject permission
Review bucket policies for deny rules
Test with AWS CLI: aws s3 cp test.txt s3://your-bucket/

R2 endpoint connection timeout

Symptoms: Connection timeouts, failed uploadsCauses:

Incorrect endpoint URL
Firewall blocking Cloudflare IPs
Invalid account ID

Solutions:

Verify endpoint format: https://<ACCOUNT_ID>.r2.cloudflarestorage.com
Check firewall rules allow HTTPS to Cloudflare IPs
Confirm account ID in Cloudflare dashboard
Test with curl: curl -I https://<ACCOUNT_ID>.r2.cloudflarestorage.com

Backfill overwhelming upload queue

Symptoms: Queue at max size immediately after enabling backfillCauses:

Large number of existing tasks
Backfill queuing faster than upload processing

Solutions:

Disable backfill temporarily: "backfillEnabled": false
Let steady-state queue drain first
Increase batchSize and decrease intervalMs
Consider maxQueueSize increase during backfill period
Re-enable backfill once queue is stable

Debug Logging

Enable debug logging to diagnose sync issues:

Check extension developer console (Help → Toggle Developer Tools)
Look for [ClineBlobStorage] and [SyncWorker] log entries
Failed uploads log error messages with details

Testing Configuration

Use the built-in test connection feature:

// Programmatic test (for custom integrations)
import { testPromptUploading } from '@/core/controller/state/testPromptUploading'

await testPromptUploading(controller)
// Returns: { success: boolean, message: string }

Data Format Reference

Conversation File Schema

Uploaded api_conversation_history.json files contain an array of messages:

[
  {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "Create a React component for a todo list"
      }
    ]
  },
  {
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "I'll create a todo list component..."
      },
      {
        "type": "tool_use",
        "id": "toolu_123",
        "name": "write_to_file",
        "input": {
          "path": "TodoList.tsx",
          "content": "..."
        }
      }
    ]
  }
]

This follows the Anthropic Messages API format.

Metadata Schema

Task metadata includes:

{
  "taskId": "1234567890",
  "createdAt": "2026-03-05T10:30:00Z",
  "lastModified": "2026-03-05T11:45:00Z",
  "modelInfo": {
    "id": "claude-sonnet-4",
    "provider": "anthropic"
  },
  "tokensUsed": {
    "input": 1250,
    "output": 3400
  }
}

Best Practices

Start Small

Test with a single team or project before rolling out organization-wide.

Monitor Costs

Set up billing alerts and review storage usage monthly.

Secure Credentials

Use dedicated IAM users with minimal permissions and rotate keys regularly.

Plan Retention

Define and implement data retention policies based on compliance needs.

OpenTelemetry

Configure metrics and logs export for comprehensive observability

Telemetry

Learn about Cline’s built-in anonymous usage tracking

Remote Configuration

Understand the remote configuration system

Enterprise Solutions

​Overview

Compliance Ready

Audit Trail

Usage Analysis

Disaster Recovery

​How It Works

​Storage Architecture

​What Gets Stored

​What’s NOT Stored

​Storage Path Pattern

​Configuration

​Schema

​Configuration Fields

​Core Settings

​Access Settings (S3/R2)

​Sync Worker Settings

​Setup Guides

​AWS S3 Configuration

​Optional: Lifecycle Policies

​Cloudflare R2 Configuration

​Cost Advantages

​Sync Worker Behavior

​Queue Management

​Failure Handling

​Backfill Mode

​Monitoring & Observability

​Integration with OpenTelemetry

​CloudWatch Monitoring (S3)

​R2 Analytics

​Security & Compliance

​Encryption

​Access Control

​Audit Logging

​Data Retention

​Troubleshooting

​Common Issues

​Debug Logging

​Testing Configuration

​Data Format Reference

​Conversation File Schema

​Metadata Schema

​Best Practices

Start Small

Monitor Costs

Secure Credentials

Plan Retention

​See Also

OpenTelemetry

Telemetry

Remote Configuration

Overview

How It Works

Storage Architecture

What Gets Stored

What’s NOT Stored

Storage Path Pattern

Configuration

Schema

Configuration Fields

Core Settings

Access Settings (S3/R2)

Sync Worker Settings

Setup Guides

AWS S3 Configuration

Optional: Lifecycle Policies

Cloudflare R2 Configuration

Cost Advantages

Sync Worker Behavior

Queue Management

Failure Handling

Backfill Mode

Monitoring & Observability

Integration with OpenTelemetry

CloudWatch Monitoring (S3)

R2 Analytics

Security & Compliance

Encryption

Access Control

Audit Logging

Data Retention

Troubleshooting

Common Issues

Debug Logging

Testing Configuration

Data Format Reference

Conversation File Schema

Metadata Schema

Best Practices

See Also