File Operations

The primitive files command group provides tools for uploading and managing files on the Primitive platform. Files can be stored as private or public resources and organized with custom key prefixes.

File Upload

primitive files upload <path> [options]

Upload files to the Primitive platform with various configuration options.

# Basic file upload
primitive files upload /path/to/file.txt

# Upload a directory (uploads all files recursively)
primitive files upload /path/to/directory/

# Upload with specific options
primitive files upload --public --key-prefix "scripts/" ./my-script.py

Upload Options

--public / -p

Make the uploaded file publicly accessible.

# Upload as public file
primitive files upload --public ./README.md

# Public files are accessible via direct URLs
primitive files upload -p ./documentation.pdf

Public vs Private Files:

• Private: Only accessible within your organization
• Public: Accessible via direct URLs without authentication
• Default: Files are private unless --public flag is used

--key-prefix / -k

Organize files with custom path prefixes.

# Organize by project
primitive files upload --key-prefix "project-alpha/" ./source-code.zip

# Create nested organization
primitive files upload --key-prefix "docs/api/" ./api-reference.md

# Multiple levels of organization
primitive files upload --key-prefix "builds/v1.2.3/artifacts/" ./build-output.tar.gz

Key Prefix Benefits:

• Organize files in logical hierarchies
• Avoid filename conflicts
• Enable bulk operations on file groups
• Simplify file discovery and management

--direct

Upload files directly to storage, bypassing the API for large files.

# Direct upload for large files
primitive files upload --direct ./large-dataset.zip

# Combine with other options
primitive files upload --direct --public --key-prefix "datasets/" ./big-file.tar.gz

When to Use Direct Upload:

• Large files (>100MB recommended)
• Better performance for big uploads
• Reduced API server load
• More reliable for unstable connections

Upload Modes

API Upload (Default)

Files are uploaded through the Primitive API server:

• Processed and validated by the platform
• Integrated with platform features (metadata, indexing)
• Subject to API rate limits and size restrictions
• Best for: Small to medium files, files requiring processing

Direct Upload

Files are uploaded directly to storage:

• Bypasses API for improved performance
• Better for large files and bulk uploads
• Less processing overhead
• Best for: Large files, datasets, archives

File Organization

Key Prefixes

Use key prefixes to create logical file organization:

# Project-based organization
primitive files upload --key-prefix "project-a/src/" ./source/
primitive files upload --key-prefix "project-a/docs/" ./documentation/
primitive files upload --key-prefix "project-a/builds/" ./releases/

# Environment-based organization
primitive files upload --key-prefix "dev/configs/" ./dev-config.yaml
primitive files upload --key-prefix "prod/configs/" ./prod-config.yaml

# Version-based organization
primitive files upload --key-prefix "v1.0/artifacts/" ./build-v1.0.zip
primitive files upload --key-prefix "v1.1/artifacts/" ./build-v1.1.zip

Naming Conventions

Best practices for file naming:

• Use descriptive, meaningful names
• Include version numbers when appropriate
• Avoid spaces (use hyphens or underscores)
• Include file extensions for proper type detection
• Consider timestamp prefixes for chronological ordering

File Types and Formats

Supported File Types

The platform supports all file types including:

• Source Code: .py, .js, .java, .cpp, .go, etc.
• Documentation: .md, .txt, .pdf, .docx, etc.
• Data Files: .json, .csv, .xml, .yaml, etc.
• Archives: .zip, .tar.gz, .7z, .rar, etc.
• Images: .png, .jpg, .gif, .svg, etc.
• Binary Files: .exe, .dll, .so, .dylib, etc.

File Processing

Different file types may receive different processing:

• Text Files: Content indexing and search
• Archives: Automatic extraction and listing
• Images: Thumbnail generation and metadata extraction
• Code Files: Syntax highlighting and analysis
• Data Files: Schema detection and validation

Output and Response

Successful Upload

{
  "data": {
    "uploadFile": {
      "id": "file_abc123",
      "key": "scripts/my-script.py",
      "url": "https://storage.primitive.tech/files/scripts/my-script.py",
      "size": 1024,
      "contentType": "text/x-python",
      "isPublic": false,
      "createdAt": "2024-12-10T12:00:00Z"
    }
  }
}

Error Response

{
  "errors": [
    {
      "message": "File upload failed: insufficient storage quota",
      "code": "STORAGE_QUOTA_EXCEEDED"
    }
  ]
}

Storage Quotas and Limits

File Size Limits

• API Upload: Typically 100MB per file
• Direct Upload: Much larger files supported (GB+)
• Organization Limits: May vary by subscription plan

Storage Quotas

• Total storage per organization
• Number of files per organization
• Bandwidth limits for public files
• Retention policies for temporary files

Monitoring Usage

# Check organization storage usage
primitive organizations list

# Monitor file upload status
primitive --json files upload large-file.zip

Security and Access Control

File Permissions

• Private Files: Accessible only to organization members
• Public Files: Accessible via direct URLs
• Organization Control: Admin can manage file access policies

Authentication

• All uploads require valid authentication
• File access respects organization membership
• API keys provide programmatic access

Encryption

• Files encrypted at rest in storage
• Secure transmission during upload
• Private file URLs include access tokens

Troubleshooting

Upload Failures

Authentication Issues:

# Verify authentication
primitive whoami

# Reconfigure if needed
primitive config

File Not Found:

# Check file path
ls -la /path/to/file.txt

# Use absolute paths if needed
primitive files upload /absolute/path/to/file.txt

Network Issues:

# Try with debug output
primitive --debug files upload ./file.txt

# Test connectivity
primitive whoami

# Try direct upload for large files
primitive files upload --direct ./large-file.zip

Performance Issues

Slow Uploads:

# Use direct upload for large files
primitive files upload --direct ./big-file.zip

# Check network connectivity
ping api.primitive.tech

# Monitor upload progress
primitive --debug files upload ./file.txt

Quota Exceeded:

# Check organization limits
primitive organizations list

# Clean up old files if possible
# Consider upgrading storage plan

Best Practices

1. Use Key Prefixes: Organize files with logical prefixes
2. Choose Upload Mode: Use direct upload for large files
3. Public vs Private: Carefully consider file visibility
4. Descriptive Names: Use clear, meaningful file names
5. Monitor Quotas: Track storage usage and limits
6. Security: Protect sensitive files as private
7. Cleanup: Remove unnecessary files periodically

Example Workflows

Project File Upload

# Upload project source code
primitive files upload --key-prefix "project-alpha/src/" ./src/

# Upload documentation
primitive files upload --public --key-prefix "project-alpha/docs/" ./docs/

# Upload build artifacts
primitive files upload --key-prefix "project-alpha/releases/v1.0/" ./dist/

Data Pipeline Files

# Upload input datasets
primitive files upload --key-prefix "datasets/input/" ./raw-data/

# Upload processing scripts
primitive files upload --key-prefix "scripts/processing/" ./process.py

# Upload results
primitive files upload --public --key-prefix "results/2024-12/" ./output/

Large File Upload

# Upload large archive directly
primitive files upload --direct --key-prefix "backups/" ./backup-2024-12.tar.gz

# Monitor progress with debug
primitive --debug files upload --direct ./large-dataset.zip

# Verify upload success
primitive --json files upload --direct ./file.zip

Public Documentation

# Upload public API documentation
primitive files upload --public --key-prefix "docs/api/v1/" ./api-docs/

# Upload public assets
primitive files upload --public --key-prefix "assets/images/" ./images/

# Upload public downloads
primitive files upload --public --key-prefix "downloads/" ./releases/