Files & Readings

Early Access - The Dcycle CLI is currently available for enterprise customers. Contact us to learn more about access.

Overview

The Files module lets you upload documents (invoices, utility bills, waste certificates), view extracted readings, correct parsed data, and create linked records — all from the terminal. The CLI uses a presigned upload flow by default:

Request a presigned URL from POST /v1/files/presigned-urls
Upload the file directly to S3
Confirm the upload with PATCH /v1/files/batch-update

This means uploads can run autonomously from scripts and CI jobs while still triggering the normal file classification and extraction pipeline.

Upload a File

dcy file upload ./invoice.pdf

Output:

Uploading invoice.pdf (245.00 KB)
ID: 550e8400-e29b-41d4-a716-446655440000
Name: invoice
Extension: PDF
MIME Type: application/pdf
Size: 245 KB
Status: uploaded
Owner: Jane Doe
Created: 2024-03-15

Upload Flags

Flag	Required	Default	Description
`--folder-id`	No	—	Target folder UUID
`--project-id`	No	—	Project UUID to link after upload
`--mode`	No	`presigned`	Upload mode: `presigned` (direct-to-S3) or `multipart` (legacy backend upload)
`--org`	No	—	Organization ID override

Upload Examples

# Upload into a specific folder
dcy file upload ./invoice.pdf --folder-id <folder-id>

# Upload and link to a project
dcy file upload ./invoice.pdf --project-id <project-id>

# Use legacy multipart upload (for troubleshooting)
dcy file upload ./invoice.pdf --mode multipart

# JSON output for scripting
dcy file upload ./invoice.pdf --format json

When --project-id is present, the CLI passes it to the batch-update step so the backend creates file_project associations automatically after the S3 upload succeeds.

List Files

dcy file list

# Short alias
dcy file ls

Output:

Showing 5 of 42 files
550e8400-... | invoice-march   | PDF  | 245 KB | uploaded | Jane Doe
661f9511-... | utility-bill    | PDF  | 180 KB | uploaded | John Smith
772a0622-... | waste-cert-q1   | XLSX | 95 KB  | uploaded | Jane Doe
883b1733-... | gas-invoice     | PDF  | 310 KB | uploaded | John Smith
994c2844-... | water-readings  | CSV  | 12 KB  | uploaded | Jane Doe

List Flags

Flag	Default	Description
`--name`, `-n`	—	Filter by file name (partial match)
`--extension`, `-e`	—	Filter by file extension (e.g. `pdf`, `xlsx`)
`--mime-type`	—	Filter by MIME type
`--from-date`	—	Filter from date (YYYY-MM-DD)
`--to-date`	—	Filter to date (YYYY-MM-DD)
`--status`	`uploaded`	Filter by status
`--owner-id`	—	Filter by owner user UUID
`--sort-by`, `-s`	—	Sort by: `name`, `extension`, `status`, `size`, `date`
`--sort-order`, `-o`	`asc`	Sort order: `asc` or `desc`
`--page`	`1`	Page number
`--size`	`50`	Page size
`--org`	—	Organization ID override

List Examples

# Find PDF files
dcy file list --extension pdf

# Files uploaded in a date range
dcy file list --from-date 2024-01-01 --to-date 2024-03-31

# Sort by size (largest first)
dcy file list --sort-by size --sort-order desc

# Search by name
dcy file list --name "invoice"

# JSON output for scripting
dcy file list --format json | jq '.[] | {id, name, status}'

Show File Details

dcy file show <file-id>

Output:

ID: 550e8400-e29b-41d4-a716-446655440000
Name: invoice-march
Extension: PDF
MIME Type: application/pdf
Size: 245 KB
Status: uploaded
Owner: Jane Doe
Owner Email: jane@company.com
URL: https://...
Tags: electricity, q1
Created: 2024-03-15
Updated: 2024-03-15

Delete a File

# Interactive confirmation
dcy file delete <file-id>

# Skip confirmation
dcy file delete <file-id> --yes

Flag	Default	Description
`--yes`, `-y`	`false`	Skip confirmation prompt
`--org`	—	Organization ID override

Recover a Deleted File

Restore a previously deleted file:

dcy file recover <file-id>

Retry File Processing

If a file was uploaded and classified but hasn’t produced a reading, re-queue it for processing:

dcy file process <file-id>

Output:

processing event queued for file 550e8400-...

This sends a PROCESS_DOCUMENT event to the backend pipeline. Use it when a file is stuck in uploaded status or when the extraction pipeline needs to re-run.

File Readings

File readings contain the data extracted from uploaded documents by the AI classification and parsing pipeline.

List Readings

dcy file reading list

# Short alias
dcy file reading ls

Output:

Showing 5 of 15 file readings
550e8400-... | invoice-march   | electricity | linked=true  | reading=completed | reading_id=abc123-...
661f9511-... | utility-bill    | natural_gas | linked=true  | reading=completed | reading_id=def456-...
772a0622-... | waste-cert-q1   | waste       | linked=false | reading=completed | reading_id=ghi789-...
883b1733-... | gas-invoice     | natural_gas | linked=false | reading=pending   | reading_id=jkl012-...
994c2844-... | water-readings  | water       | linked=false | reading=(none)    | reading_id=

List Reading Flags

Flag	Default	Description
`--file-id`	—	Filter by file ID (repeatable for multiple files)
`--folder-id`	—	Filter by folder ID
`--project-id`	—	Filter by project ID
`--linked`	—	Filter by linked status: `true` or `false`
`--name`	—	Filter by file name
`--category`	—	Filter by reading category (repeatable)
`--page`	`1`	Page number
`--size`	`50`	Page size
`--org`	—	Organization ID override

List Reading Examples

# Filter by category
dcy file reading list --category electricity
dcy file reading list --category water --category waste

# Find unlinked readings (not yet converted to records)
dcy file reading list --linked false

# Filter by specific file
dcy file reading list --file-id <file-id>

# Filter by folder
dcy file reading list --folder-id <folder-id>

# JSON output
dcy file reading list --format json | jq '.[] | select(.linked == false) | .id'

Show a File’s Reading

View the parsed reading content for a specific file:

dcy file reading show <file-id>

Output:

File ID: 550e8400-e29b-41d4-a716-446655440000
Name: invoice-march
Category: electricity
Status: uploaded
Linked: true
Tags: electricity, q1
Reading ID: abc123-def456-...
Reading Status: completed
Reading Items: 3

Correct Reading Content

If the extracted data has errors, prepare a JSON file with the corrected content and update the reading:

dcy file reading update <file-reading-id> --content-file ./reading.json

Flag	Required	Description
`--content-file`	Yes	Path to JSON file with corrected items
`--org`	No	Organization ID override

The JSON file can be in any of these formats: Full content object:

{
  "content": {
    "items": [
      {"type": "electricity", "start_date": "2024-01-01", "consumption": 4500}
    ]
  }
}

Items wrapper:

{
  "items": [
    {"type": "electricity", "start_date": "2024-01-01", "consumption": 4500}
  ]
}

Raw items array:

[
  {"type": "electricity", "start_date": "2024-01-01", "consumption": 4500}
]

Create Records from Readings

Convert a parsed reading into invoices or waste records, assigning facility allocations:

# Single facility (100%)
dcy file reading create-records <file-reading-id> \
  --facility <facility-id>=1.0

Output:

Created 3 records from file reading abc123-...
rec-001-... | electricity | facility=fac-001-...
rec-002-... | electricity | facility=fac-001-...
rec-003-... | electricity | facility=fac-001-...

Split Across Multiple Facilities

Allocate the reading’s data across facilities by percentage (total must be ≤ 1.0):

dcy file reading create-records <file-reading-id> \
  --facility <facility-a>=0.6 \
  --facility <facility-b>=0.4 \
  --project-id <project-id>

Flag	Required	Description
`--facility`	Yes	Facility allocation as `facility-id=percentage` (repeatable)
`--project-id`	No	Project UUID to link created records
`--org`	No	Organization ID override

The backend currently processes one file reading per create-records request.

Typical Workflows

Upload and Process Invoice

Upload an invoice PDF, wait for extraction, then create invoice records:

# 1. Upload the file
FILE_ID=$(dcy file upload ./invoice.pdf --project-id "$PROJECT_ID" --format json | jq -r '.id')
echo "Uploaded: $FILE_ID"

# 2. Check if the reading is ready (may take a few seconds)
dcy file reading show $FILE_ID

# 3. If no reading yet, re-trigger processing
dcy file process $FILE_ID

# 4. Once reading is complete, get the reading ID
READING_ID=$(dcy file reading list --file-id $FILE_ID --format json | jq -r '.[0].reading.id')

# 5. Create invoice records from the reading
dcy file reading create-records $READING_ID --facility "$FACILITY_ID"=1.0

Batch Upload Documents

Upload all PDFs in a directory:

for file in ./invoices/*.pdf; do
  echo "Uploading $file..."
  dcy file upload "$file" --folder-id "$FOLDER_ID" --format json
done

Find Unlinked Readings

Identify files that have been parsed but not yet converted to records:

# List unlinked readings
dcy file reading list --linked false --format json \
  | jq '.[] | {id, name, category, reading_id: .reading.id}'

Correct and Re-create Records

Fix extracted data and create records from the corrected reading:

# 1. Export current reading content
dcy file reading show <file-id> --format json | jq '.reading.content' > reading.json

# 2. Edit reading.json to fix errors

# 3. Update the reading
dcy file reading update <reading-id> --content-file reading.json

# 4. Create records from the corrected reading
dcy file reading create-records <reading-id> --facility <facility-id>=1.0

CI/CD Automation

Upload files from a CI pipeline using API key authentication:

#!/usr/bin/env bash
set -euo pipefail

export DCYCLE_API_KEY="$API_KEY"
export DCYCLE_ORG_ID="$ORG_ID"

for file in ./artifacts/*.pdf; do
  result=$(dcy file upload "$file" --project-id "$PROJECT_ID" --format json)
  echo "Uploaded $(basename "$file"): $(echo "$result" | jq -r '.id')"
done

Next Steps

Invoices

Manage energy invoices created from file readings

Data Imports

Bulk import CSV/Excel with guided mapping and validation

Projects

Organize files and emissions data into sustainability projects

Configuration

Set up environments and API keys for automation

MCP Tools

Query files from AI assistants via MCP

Getting Started

Commands

Examples

Overview

Upload a File

Upload Flags

Upload Examples

List Files

List Flags

List Examples

Show File Details

Delete a File

Recover a Deleted File

Retry File Processing

File Readings

List Readings

List Reading Flags

List Reading Examples

Show a File’s Reading

Correct Reading Content

Create Records from Readings

Split Across Multiple Facilities

Typical Workflows

Upload and Process Invoice

Batch Upload Documents

Find Unlinked Readings

Correct and Re-create Records

CI/CD Automation

Next Steps

Invoices

Data Imports

Projects

Configuration

MCP Tools

​Overview

​Upload a File

​Upload Flags

​Upload Examples

​List Files

​List Flags

​List Examples

​Show File Details

​Delete a File

​Recover a Deleted File

​Retry File Processing

​File Readings

​List Readings

​List Reading Flags

​List Reading Examples

​Show a File’s Reading

​Correct Reading Content

​Create Records from Readings

​Split Across Multiple Facilities

​Typical Workflows

​Upload and Process Invoice

​Batch Upload Documents

​Find Unlinked Readings

​Correct and Re-create Records

​CI/CD Automation

​Next Steps

Invoices

Data Imports

Projects

Configuration

MCP Tools

Overview

Upload a File

Upload Flags

Upload Examples

List Files

List Flags

List Examples

Show File Details

Delete a File

Recover a Deleted File

Retry File Processing

File Readings

List Readings

List Reading Flags

List Reading Examples

Show a File’s Reading

Correct Reading Content

Create Records from Readings

Split Across Multiple Facilities

Typical Workflows

Upload and Process Invoice

Batch Upload Documents

Find Unlinked Readings

Correct and Re-create Records

CI/CD Automation

Next Steps