### Install Task on macOS/Linux

Source: https://github.com/tgdrive/teldrive/blob/main/CONTRIBUTING.md

Installs the Task build tool using curl. Ensure Go is installed and in your PATH.

```sh
curl https://instl.vercel.app/go-task/task | bash
```

--------------------------------

### Install Teldrive

Source: https://context7.com/tgdrive/teldrive/llms.txt

Use the one-line installer for macOS/Linux or Windows PowerShell. Verify the installation with the `teldrive version` command.

```bash
# macOS/Linux
curl -sSL instl.vercel.app/teldrive | bash
```

```powershell
# Windows PowerShell
powershell -c "irm https://instl.vercel.app/teldrive?platform=windows|iex"
```

```bash
# Verify installation
teldrive version
```

--------------------------------

### Install Dependencies

Source: https://github.com/tgdrive/teldrive/blob/main/CONTRIBUTING.md

Installs project dependencies using the Task build tool. Assumes Task is installed and the repository is cloned.

```bash
task deps
```

--------------------------------

### Start PostgreSQL Database

Source: https://github.com/tgdrive/teldrive/blob/main/tests/integration/README.md

Use this command to start the PostgreSQL database in detached mode for integration tests. Ensure Docker is installed and running.

```bash
docker compose -f tests/docker-compose.test.yml up -d
```

--------------------------------

### Example PostgreSQL Connection String

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/getting-started/prerequisites.md

An example of a PostgreSQL connection string to use with Teldrive when running locally with Docker. Adjust credentials and host as necessary.

```text
postgres://teldrive:secret@localhost:5432/teldrive?sslmode=disable
```

--------------------------------

### Install Teldrive Rclone Backend

Source: https://context7.com/tgdrive/teldrive/llms.txt

Use these commands to install the Teldrive Rclone backend on macOS/Linux or Windows.

```bash
# macOS/Linux
curl -sSL instl.vercel.app/rclone | bash
```

```powershell
# Windows
powershell -c "irm https://instl.vercel.app/rclone?platform=windows|iex"
```

--------------------------------

### Install Task on Windows

Source: https://github.com/tgdrive/teldrive/blob/main/CONTRIBUTING.md

Installs the Task build tool using PowerShell. Requires PowerShell and internet access.

```powershell
powershell -c "irm https://instl.vercel.app/go-task/task?platform=windows|iex"
```

--------------------------------

### Start imgproxy Service

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/getting-started/advanced.md

Command to start the imgproxy service using docker compose after defining its configuration.

```sh
docker compose up -d
```

--------------------------------

### Install Teldrive on Windows

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/getting-started/installation.md

Use this PowerShell command to install Teldrive on Windows systems.

```powershell
powershell -c "irm https://instl.vercel.app/teldrive?platform=windows|iex"
```

--------------------------------

### Structured Logging with Zap

Source: https://github.com/tgdrive/teldrive/blob/main/AGENTS.md

Example of using the `zap` logger for structured logging with key-value pairs.

```go
logging.FromContext(ctx).Info("User logged in", zap.String("user_id", "123"), zap.String("ip_address", "192.168.1.1"))
```

--------------------------------

### Install Teldrive rclone backend on Windows

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/guides/rclone.md

Installs the Teldrive rclone backend using PowerShell. Ensure you have a running Teldrive server and a Teldrive login.

```powershell
powershell -c "irm https://instl.vercel.app/rclone?platform=windows|iex"
```

--------------------------------

### Install Docker Volume Plugin

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/guides/jellyfin.md

Installs the rclone Docker volume plugin. Ensure you use the correct plugin tag for your architecture and adjust paths if necessary.

```bash
docker plugin install ghcr.io/tgdrive/docker-volume-rclone --alias rclone --grant-all-permissions args="--allow-other" config=/etc/rclone cache=/var/cache
```

--------------------------------

### Verify Docker Installation

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/getting-started/prerequisites.md

Commands to verify that Docker and Docker Compose are installed and accessible in your system's PATH.

```sh
docker --version
docker compose version
```

--------------------------------

### Install Teldrive rclone backend on macOS/Linux

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/guides/rclone.md

Installs the Teldrive rclone backend using curl. Ensure you have a running Teldrive server and a Teldrive login.

```sh
curl -sSL instl.vercel.app/rclone | bash
```

--------------------------------

### Run Integration Tests with Helper Script

Source: https://github.com/tgdrive/teldrive/blob/main/tests/integration/README.md

An alternative method to run integration tests using a provided shell script. This script likely encapsulates the database setup and test execution commands.

```bash
./scripts/test-integration.sh
```

--------------------------------

### Install Teldrive on macOS/Linux

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/getting-started/installation.md

Use this command to install Teldrive on macOS or Linux systems via curl.

```sh
curl -sSL instl.vercel.app/teldrive | bash
```

--------------------------------

### Automated Startup Script for Teldrive and Services

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/guides/jellyfin.md

A bash script to ensure Teldrive containers are running before creating and starting services that depend on the rclone volume. Avoid using restart policies in compose files with the rclone volume driver.

```bash
#!/bin/bash
set -e

is_container_running() {
  local container_name=$1
  docker inspect -f '{{.State.Running}}' $container_name 2>/dev/null || echo "false"
}

POLL_INTERVAL=2

CONTAINERS=("teldrive")

for container in "${CONTAINERS[@]}"; do
  while [ "$(is_container_running $container)" != "true" ]; do
    echo "Waiting for container $container to be running..."
    sleep $POLL_INTERVAL
  done
  echo "Container $container is running."
done

VOLUME_NAME="rclone"

VOLUME_EXISTS=$(docker volume inspect $VOLUME_NAME > /dev/null 2>&1 && echo "yes" || echo "no")

# Create the volume if it does not exist
if [ "$VOLUME_EXISTS" == "no" ]; then
  echo "Volume $VOLUME_NAME does not exist. Creating volume..."
  docker volume create \
    --driver rclone \
    --opt remote="teldrive_remote_name:" \
    --opt vfs_cache_max_age=7720h \
    --opt vfs_read_chunk_streams=2 \
    --opt vfs_read_chunk_size=64M \
    --opt vfs_cache_max_size=300G \
    $VOLUME_NAME
  echo "Volume $VOLUME_NAME created successfully."
else
  echo "Volume $VOLUME_NAME already exists. Skipping creation."
fi

# Add other services here which depend on the rclone volume
cd /path/to/jellyfin/compose && docker compose up -d
```

--------------------------------

### Configure Jellyfin with Teldrive Volume

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/guides/jellyfin.md

Example Docker Compose file to run Jellyfin, mounting Teldrive storage via the rclone Docker volume.

```yaml
services:
  jellyfin:
    image: jellyfin/jellyfin
    container_name: jellyfin
    volumes:
      - /path/to/config:/config
      - /path/to/cache:/cache
      - rclone:/media

volumes:
  rclone:
    external: true
```

--------------------------------

### Local PostgreSQL with Docker Compose

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/getting-started/prerequisites.md

Use this Docker Compose configuration to quickly set up a local PostgreSQL instance for Teldrive. Ensure Docker is installed and running.

```yaml
services:
  postgres:
    image: groonga/pgroonga:latest-alpine-17
    restart: unless-stopped
    environment:
      POSTGRES_USER: teldrive
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: teldrive
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

```

--------------------------------

### Common rclone commands for Teldrive

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/guides/rclone.md

Provides examples of frequently used rclone commands for interacting with Teldrive, such as listing, copying, syncing, and mounting.

```sh
rclone lsd teldrive:
```

```sh
rclone ls teldrive:
```

```sh
rclone copy ./local-folder teldrive:/backup
```

```sh
rclone sync ./media teldrive:/media
```

```sh
rclone mount teldrive:/ ~/mnt/teldrive
```

```sh
rclone link teldrive:/path/to/file
```

--------------------------------

### Get User Configuration

Source: https://context7.com/tgdrive/teldrive/llms.txt

Retrieves the current user's configuration settings, including channel ID and configured bots. Requires an authorization token.

```bash
# Get user configuration
curl -X GET http://localhost:8080/api/users/config \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Get File Details by ID

Source: https://context7.com/tgdrive/teldrive/llms.txt

Retrieve detailed information about a specific file using its unique ID. Requires an authorization token.

```bash
curl -X GET http://localhost:8080/api/files/{file-id} \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Display teldrive version

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/cli/version.md

Use this command to check the installed version of teldrive. This command accepts no flags.

```sh
teldrive version
```

--------------------------------

### Get Uploaded Parts

Source: https://context7.com/tgdrive/teldrive/llms.txt

Retrieves a list of all uploaded parts for a given upload session. Requires the upload ID and an authorization token.

```bash
# Get all uploaded parts for an upload session
curl -X GET http://localhost:8080/api/uploads/{upload-id} \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Get Storage Statistics by Category

Source: https://context7.com/tgdrive/teldrive/llms.txt

Retrieve statistics about storage usage, broken down by file category. Requires an authorization token.

```bash
curl -X GET http://localhost:8080/api/files/categories \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Set up Frontend

Source: https://github.com/tgdrive/teldrive/blob/main/CONTRIBUTING.md

Sets up the frontend by pulling the latest release. This command is specific to the TelDrive project's build process.

```bash
task ui
```

--------------------------------

### Preview Documentation Locally

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/getting-started/installation.md

Use this command to preview the in-repo documentation site locally when working from the Teldrive repository.

```sh
task docs:dev
```

--------------------------------

### Run Teldrive from Source

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/getting-started/installation.md

If you are working from the Teldrive repository, use these task commands to set up dependencies, build the UI, and run the application.

```sh
task deps
task ui
task run
```

--------------------------------

### Run Teldrive from Binary

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/getting-started/usage.md

Execute the Teldrive binary with a specified configuration file. Alternatively, if the config is in the default location (~/.teldrive/config.toml), you can run it without specifying the config path.

```sh
./teldrive run --config ./config.toml
```

```sh
teldrive run
```

--------------------------------

### GET /api/periodic-jobs

Source: https://context7.com/tgdrive/teldrive/llms.txt

Lists all configured periodic jobs.

```APIDOC
## GET /api/periodic-jobs

### Description
Retrieves a list of all configured periodic jobs.

### Method
GET

### Endpoint
/api/periodic-jobs

### Parameters
None

### Request Example
```bash
curl -X GET http://localhost:8080/api/periodic-jobs \
  -H "Authorization: Bearer <token>"
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the periodic job.
- **name** (string) - The name of the periodic job.
- **kind** (string) - The type of job the periodic job triggers (e.g., "sync.run").
- **enabled** (boolean) - Indicates if the periodic job is currently enabled.
- **cronExpression** (string) - The cron expression defining the schedule for the job.
- **createdAt** (string) - The timestamp when the periodic job was created.
- **updatedAt** (string) - The timestamp when the periodic job was last updated.

#### Response Example
```json
[
  {
    "id": "job-uuid",
    "name": "Daily Backup",
    "kind": "sync.run",
    "enabled": true,
    "cronExpression": "0 2 * * *",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T10:00:00Z"
  }
]
```
```

--------------------------------

### Set up imgproxy for Thumbnail Resizing

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/getting-started/advanced.md

This docker-compose configuration sets up imgproxy as a service for handling image thumbnail resizing. It allows all origins and enforces WebP format.

```yaml
services:
  imgproxy:
    image: darthsim/imgproxy
    restart: unless-stopped
    environment:
      IMGPROXY_ALLOW_ORIGIN: "*"
      IMGPROXY_ENFORCE_WEBP: true
    ports:
      - "8000:8080"
```

--------------------------------

### Run Integration Tests with Go

Source: https://github.com/tgdrive/teldrive/blob/main/tests/integration/README.md

Execute integration tests using the Go test command. Set the TEST_DATABASE_URL environment variable to connect to the test database. The -count=1 flag ensures tests are not cached.

```bash
TEST_DATABASE_URL=postgres://teldrive_test:teldrive_test@localhost:55432/teldrive_test?sslmode=disable go test ./tests/integration/... -count=1
```

--------------------------------

### GET /api/jobs/{job-id}

Source: https://context7.com/tgdrive/teldrive/llms.txt

Retrieves the status of a specific job.

```APIDOC
## GET /api/jobs/{job-id}

### Description
Retrieves the status of a specific job.

### Method
GET

### Endpoint
/api/jobs/{job-id}

### Parameters
#### Path Parameters
- **job-id** (string) - Required - The ID of the job to retrieve.

### Request Example
```bash
curl -X GET http://localhost:8080/api/jobs/{job-id} \
  -H "Authorization: Bearer <token>"
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier for the job.
- **kind** (string) - The type of job (e.g., "sync.run").
- **queue** (string) - The queue the job belongs to.
- **state** (string) - The current state of the job (e.g., "completed").
- **attempt** (integer) - The current attempt number for the job.
- **maxAttempts** (integer) - The maximum number of attempts allowed for the job.
- **createdAt** (string) - The timestamp when the job was created.
- **startedAt** (string) - The timestamp when the job started execution.
- **finalizedAt** (string) - The timestamp when the job finished execution.
- **output** (object) - Contains details about the job's output, including progress and data processed.
  - **progress** (object)
    - **total** (integer) - Total units of work.
    - **done** (integer) - Units of work completed.
    - **percent** (integer) - Percentage of work completed.
  - **data** (object) - Specific data related to the job's execution (e.g., files processed, bytes transferred).

#### Response Example
```json
{
  "id": 12345,
  "kind": "sync.run",
  "queue": "default",
  "state": "completed",
  "attempt": 1,
  "maxAttempts": 8,
  "createdAt": "2024-01-15T10:00:00Z",
  "startedAt": "2024-01-15T10:00:05Z",
  "finalizedAt": "2024-01-15T10:30:00Z",
  "output": {
    "progress": {"total": 50, "done": 50, "percent": 100},
    "data": {"filesProcessed": 50, "bytesTransferred": 5368709120}
  }
}
```
```

--------------------------------

### Get Pending Events

Source: https://context7.com/tgdrive/teldrive/llms.txt

Retrieve a list of pending events by polling the API.

```APIDOC
## GET /api/events

### Description
Retrieves a list of pending events.

### Method
GET

### Endpoint
/api/events

### Request Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the event.
- **type** (string) - The type of the event (e.g., "files.created").
- **createdAt** (string) - The timestamp when the event was created.
- **source** (object) - Information about the source of the event.
  - **id** (string) - The ID of the source object.
  - **name** (string) - The name of the source object.
  - **type** (string) - The type of the source object (e.g., "file").
  - **parentId** (string) - The ID of the parent object.

### Response Example
```json
[
  {
    "id": "event-uuid",
    "type": "files.created",
    "createdAt": "2024-01-15T10:30:00Z",
    "source": {
      "id": "file-uuid",
      "name": "uploaded-file.mp4",
      "type": "file",
      "parentId": "parent-folder-uuid"
    }
  }
]
```
```

--------------------------------

### Run Teldrive Server

Source: https://context7.com/tgdrive/teldrive/llms.txt

Instructions for running the Teldrive server using Docker Compose or directly via binary. Supports configuration via file or command-line flags.

```bash
# Using Docker Compose
cat > docker-compose.yml << 'EOF'
services:
  teldrive:
    image: ghcr.io/tgdrive/teldrive
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./config.toml:/config.toml:ro
EOF
docker compose up -d
```

```bash
# Using binary with config file
./teldrive run --config ./config.toml
```

```bash
# Using binary with default config location ($HOME/.teldrive/config.toml)
teldrive run
```

```bash
# With command-line flags
teldrive run \
  --db-data-source "postgres://user:pass@localhost/teldrive" \
  --jwt-secret "your-secret-key" \
  --jwt-allowed-users "username1,username2" \
  --server-port 8080
```

--------------------------------

### Get Category Statistics

Source: https://context7.com/tgdrive/teldrive/llms.txt

Retrieve storage statistics aggregated by file category.

```APIDOC
## GET /api/files/categories

### Description
Retrieves statistics about file storage, grouped by category.

### Method
GET

### Endpoint
/api/files/categories

### Response
#### Success Response (200)
- Returns an object where keys are category names and values are statistics for that category (e.g., total size, file count).

### Response Example
```json
{
  "document": {
    "totalSize": 1073741824,
    "fileCount": 100
  },
  "video": {
    "totalSize": 5368709120,
    "fileCount": 50
  }
}
```
```

--------------------------------

### Get File by ID

Source: https://context7.com/tgdrive/teldrive/llms.txt

Retrieve details of a specific file or folder using its ID.

```APIDOC
## GET /api/files/{file-id}

### Description
Retrieves the metadata for a specific file or folder identified by its ID.

### Method
GET

### Endpoint
/api/files/{file-id}

### Path Parameters
- **file-id** (string) - Required - The unique identifier of the file or folder.

### Response
#### Success Response (200)
- **id** (string) - Unique identifier.
- **name** (string) - Name of the file or folder.
- **type** (string) - Type of item ('file' or 'folder').
- **mimeType** (string) - MIME type of the file.
- **size** (integer) - Size of the file in bytes.
- **path** (string) - The full path of the item.
- **channelId** (integer) - Channel ID associated with the file.
- **encrypted** (boolean) - Whether the file is encrypted.
- **hash** (string) - Hash of the file content.
- **updatedAt** (string) - Timestamp of the last update.

### Response Example
```json
{
  "id": "file-uuid",
  "name": "document.pdf",
  "type": "file",
  "mimeType": "application/pdf",
  "size": 1048576,
  "path": "/documents/2024",
  "channelId": 123456789,
  "encrypted": false,
  "hash": "blake3-tree-hash",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```
```

--------------------------------

### Minimal Teldrive Configuration

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/getting-started/usage.md

This TOML configuration sets up the database connection, allowed JWT users, and encryption key for uploads. Ensure you replace placeholder values with your actual credentials and secrets.

```toml
[db]
data-source = "postgres://teldrive:secret@localhost/postgres"

[jwt]
allowed-users = ["your_telegram_username"]
secret = "replace-with-a-random-secret"

[tg.uploads]
encryption-key = "replace-with-a-random-key"
```

--------------------------------

### Run Linter with Task

Source: https://github.com/tgdrive/teldrive/blob/main/AGENTS.md

Executes the `golangci-lint` tool to check for code style and potential issues.

```bash
task lint
```

--------------------------------

### Get Job Status

Source: https://context7.com/tgdrive/teldrive/llms.txt

Retrieve the status of a specific job using its ID. Requires an authorization token.

```bash
# Get specific job status
curl -X GET http://localhost:8080/api/jobs/{job-id} \
  -H "Authorization: Bearer <token>"
```

```json
{
  "id": 12345,
  "kind": "sync.run",
  "queue": "default",
  "state": "completed",
  "attempt": 1,
  "maxAttempts": 8,
  "createdAt": "2024-01-15T10:00:00Z",
  "startedAt": "2024-01-15T10:00:05Z",
  "finalizedAt": "2024-01-15T10:30:00Z",
  "output": {
    "progress": {"total": 50, "done": 50, "percent": 100},
    "data": {"filesProcessed": 50, "bytesTransferred": 5368709120}
  }
}
```

--------------------------------

### Get Upload Statistics

Source: https://context7.com/tgdrive/teldrive/llms.txt

Retrieves upload statistics for a specified number of past days. Requires an authorization token.

```bash
# Get upload statistics for last 7 days
curl -X GET "http://localhost:8080/api/uploads/stats?days=7" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Run All Go Tests

Source: https://github.com/tgdrive/teldrive/blob/main/AGENTS.md

Executes all tests across all packages in the project.

```bash
go test ./...
```

--------------------------------

### Access Shared Content - Get Info

Source: https://context7.com/tgdrive/teldrive/llms.txt

Retrieves information about a shared item using its share ID. This is a public endpoint.

```bash
# Get share information (public endpoint)
curl -X GET http://localhost:8080/api/shares/{share-id}
```

--------------------------------

### Build TelDrive

Source: https://github.com/tgdrive/teldrive/blob/main/CONTRIBUTING.md

Builds both the frontend and backend components of TelDrive using the Task build tool.

```bash
task
```

--------------------------------

### Get Upload Statistics Response

Source: https://context7.com/tgdrive/teldrive/llms.txt

Provides daily upload statistics, including the date and total uploaded size in bytes.

```json
[
  {"uploadDate": "2024-01-15T00:00:00Z", "totalUploaded": 10737418240},
  {"uploadDate": "2024-01-14T00:00:00Z", "totalUploaded": 5368709120}
]
```

--------------------------------

### Format Go Code

Source: https://github.com/tgdrive/teldrive/blob/main/AGENTS.md

Applies standard Go formatting to all files in the project.

```bash
go fmt ./...
```

--------------------------------

### Get User Profile Photo

Source: https://context7.com/tgdrive/teldrive/llms.txt

Downloads the user's profile photo. The output is saved to 'profile.jpg'. Requires an authorization token.

```bash
# Get user profile photo
curl -X GET http://localhost:8080/api/users/profile \
  -H "Authorization: Bearer <token>" \
  -o profile.jpg
```

--------------------------------

### Create Files and Folders

Source: https://context7.com/tgdrive/teldrive/llms.txt

Create new folders or file entries.

```APIDOC
## POST /api/files

### Description
Creates a new folder or a file entry. For files, this typically precedes the actual upload of file content.

### Method
POST

### Endpoint
/api/files

### Request Body
- **name** (string) - Required - The name of the folder or file.
- **type** (string) - Required - The type of item to create ('folder' or 'file').
- **path** (string) - Optional - The parent path for the new item. Defaults to root '/'.
- **mimeType** (string) - Optional - The MIME type of the file (required if type is 'file').
- **size** (integer) - Optional - The size of the file in bytes (required if type is 'file').
- **uploadId** (string) - Optional - The ID of an ongoing upload session (required if type is 'file' and creating an entry for uploaded content).
- **encrypted** (boolean) - Optional - Whether the file should be encrypted.

### Request Example
```json
{
  "name": "My Documents",
  "type": "folder",
  "path": "/"
}
```
```json
{
  "name": "video.mp4",
  "type": "file",
  "mimeType": "video/mp4",
  "size": 104857600,
  "uploadId": "upload-session-id",
  "path": "/videos",
  "encrypted": false
}
```

### Response
#### Success Response (200 or 201)
- **id** (string) - The unique identifier of the created item.
- **name** (string) - The name of the created item.
- **type** (string) - The type of the created item ('file' or 'folder').
- **mimeType** (string) - The MIME type of the file.
- **size** (integer) - The size of the file in bytes.
- **category** (string) - The category of the file.
- **encrypted** (boolean) - Whether the item is encrypted.
- **updatedAt** (string) - Timestamp of the last update.

### Response Example
```json
{
  "id": "new-file-uuid",
  "name": "video.mp4",
  "type": "file",
  "mimeType": "video/mp4",
  "size": 104857600,
  "category": "video",
  "encrypted": false,
  "updatedAt": "2024-01-15T10:30:00Z"
}
```
```

--------------------------------

### Create Periodic Sync Job

Source: https://context7.com/tgdrive/teldrive/llms.txt

Create a new periodic sync job with detailed configuration including filters and options. Also includes a utility to test connection before creation. Requires an authorization token.

```bash
# Create periodic sync job
curl -X POST http://localhost:8080/api/periodic-jobs \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nightly Media Sync",
    "cronExpression": "0 3 * * *",
    "enabled": true,
    "args": {
      "source": "sftp://user:pass@server.com:22/media",
      "destinationDir": "/media/synced",
      "filters": {
        "include": ["*.mp4", "*.mkv"],
        "exclude": ["*.tmp"],
        "minSize": 1048576,
        "maxSize": 10737418240
      },
      "options": {
        "encrypted": false,
        "sync": true,
        "partSize": 536870912
      }
    }
  }'
```

```bash
# Test connection before creating job
curl -X POST http://localhost:8080/api/periodic-jobs/test-connection \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "rclone://remote:/path",
    "destinationDir": "/imports"
  }'
```

--------------------------------

### Get API Version Information

Source: https://context7.com/tgdrive/teldrive/llms.txt

Fetches information about the Teldrive API version, including commit SHA, Go version, OS, and architecture.

```bash
# Get API version information
curl -X GET http://localhost:8080/api/version
```

--------------------------------

### List Files in Root Folder

Source: https://context7.com/tgdrive/teldrive/llms.txt

Use this endpoint to list all files and folders directly within the root directory. Requires an authorization token.

```bash
curl -X GET "http://localhost:8080/api/files?path=/" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### List Files with Pagination and Sorting

Source: https://context7.com/tgdrive/teldrive/llms.txt

Retrieve a paginated and sorted list of files from a specified directory. Supports sorting by name and ascending order. Requires an authorization token.

```bash
curl -X GET "http://localhost:8080/api/files?path=/documents&sort=name&order=asc&limit=50&cursor=cursor-token" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Get Uploaded Parts Response

Source: https://context7.com/tgdrive/teldrive/llms.txt

A list of uploaded parts, each with its metadata including name, ID, part number, channel, size, and encryption status.

```json
[
  {"name": "video.mp4", "partId": 12345, "partNo": 1, "channelId": 123456789, "size": 536870912, "encrypted": false},
  {"name": "video.mp4", "partId": 12346, "partNo": 2, "channelId": 123456789, "size": 536870912, "encrypted": false}
]
```

--------------------------------

### Run Integration Tests with Task

Source: https://github.com/tgdrive/teldrive/blob/main/tests/integration/README.md

Execute integration tests using the 'task' command-line tool. This assumes a Taskfile.yml is configured to run integration tests.

```bash
task test:integration
```

--------------------------------

### Get File Headers Only

Source: https://context7.com/tgdrive/teldrive/llms.txt

Retrieve only the HTTP headers for a file's content endpoint without downloading the actual file data. Useful for checking metadata like size, modification date, and ETag. Requires the file ID and authorization token.

```bash
curl -I http://localhost:8080/api/files/{file-id}/content \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Create Public Share

Source: https://context7.com/tgdrive/teldrive/llms.txt

Creates a public share for a file. No additional parameters are needed beyond the file ID and authorization token.

```bash
# Create public share
curl -X POST http://localhost:8080/api/files/{file-id}/shares \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

--------------------------------

### Verify Backups with rclone ls

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/guides/db-backup.md

List backups in the remote storage to verify successful transfers.

```bash
rclone ls remote:path/to/backups
```

--------------------------------

### Caddyfile Configuration

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/guides/caddy-cloudflare.md

Configures Caddy to serve Teldrive and imgproxy, enabling compression and reverse proxying. Remove the imgproxy block if not using it.

```caddyfile
teldrive.example.com {
  encode zstd gzip
  reverse_proxy teldrive:8080
}

imgproxy.example.com {
  encode zstd gzip
  reverse_proxy imgproxy:8080
}
```

--------------------------------

### Wrap Errors with %w

Source: https://github.com/tgdrive/teldrive/blob/main/AGENTS.md

Demonstrates wrapping an error using the `%w` verb to preserve the original error context.

```go
wrappedErr := fmt.Errorf("operation failed: %w", err)
```

--------------------------------

### Complete Phone Authentication

Source: https://context7.com/tgdrive/teldrive/llms.txt

Steps to complete phone authentication: sending a verification code and then signing in with the received code and hash. Handles 2FA password if enabled.

```bash
# Send verification code
curl -X POST http://localhost:8080/api/auth/attempts/{id}/phone/send-code \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNo": "+1234567890"
  }'
```

```bash
# Sign in with received code
curl -X POST http://localhost:8080/api/auth/attempts/{id}/phone/sign-in \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNo": "+1234567890",
    "phoneCode": "12345",
    "phoneCodeHash": "hash-from-send-code"
  }'
```

```bash
# If 2FA is enabled, provide password
curl -X POST http://localhost:8080/api/auth/attempts/{id}/password \
  -H "Content-Type: application/json" \
  -d '{
    "password": "your-2fa-password"
  }'
```

--------------------------------

### Create a Folder

Source: https://context7.com/tgdrive/teldrive/llms.txt

Create a new folder within the Teldrive system. Specify the folder name, type as 'folder', and its parent path. Requires an authorization token and JSON content type.

```bash
curl -X POST http://localhost:8080/api/files \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Documents",
    "type": "folder",
    "path": "/"
  }'
```

--------------------------------

### Build Backend Only

Source: https://github.com/tgdrive/teldrive/blob/main/CONTRIBUTING.md

Builds only the backend component of TelDrive using the Task build tool.

```bash
task server
```

--------------------------------

### Copy File

Source: https://context7.com/tgdrive/teldrive/llms.txt

Create a copy of an existing file in a specified destination directory, optionally with a new name. Requires the file ID, authorization token, and JSON payload.

```bash
curl -X POST http://localhost:8080/api/files/{file-id}/copy \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "/backup",
    "newName": "document-backup.pdf"
  }'
```

--------------------------------

### List API Keys

Source: https://context7.com/tgdrive/teldrive/llms.txt

Retrieves a list of all API keys associated with the user account. Requires an authorization token.

```bash
# List API keys
curl -X GET http://localhost:8080/api/users/api-keys \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Create Channel

Source: https://context7.com/tgdrive/teldrive/llms.txt

Creates a new user channel with a specified name. Requires an authorization token and JSON content type.

```bash
# Create channel
curl -X POST http://localhost:8080/api/users/channels \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "channelName": "New Storage Channel"
  }'
```

--------------------------------

### Create a File Entry

Source: https://context7.com/tgdrive/teldrive/llms.txt

Create a file entry after uploading its parts. Requires file details like name, type, mime type, size, upload ID, and path. Requires an authorization token and JSON content type.

```bash
curl -X POST http://localhost:8080/api/files \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "video.mp4",
    "type": "file",
    "mimeType": "video/mp4",
    "size": 104857600,
    "uploadId": "upload-session-id",
    "path": "/videos",
    "encrypted": false
  }'
```

--------------------------------

### Sync Channels from Telegram

Source: https://context7.com/tgdrive/teldrive/llms.txt

Initiates a synchronization process to import channels from Telegram. Requires an authorization token.

```bash
# Sync channels from Telegram
curl -X PATCH http://localhost:8080/api/users/channels/sync \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### List All Jobs

Source: https://context7.com/tgdrive/teldrive/llms.txt

Retrieves a list of all background jobs. Requires an authorization token.

```bash
# List all jobs
curl -X GET http://localhost:8080/api/jobs \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Create Docker Network

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/guides/caddy-cloudflare.md

Creates a Docker network named 'web' for containers to communicate.

```sh
docker network create web
```

--------------------------------

### Run Go Tests with Race Detector

Source: https://github.com/tgdrive/teldrive/blob/main/AGENTS.md

Executes all tests with the race detector enabled to find data races.

```bash
go test -race ./...
```

--------------------------------

### Download File as Attachment

Source: https://context7.com/tgdrive/teldrive/llms.txt

Download a file with the 'Content-Disposition' header set to 'attachment', prompting a file download in the browser. Requires the file ID and authorization token.

```bash
curl -X GET "http://localhost:8080/api/files/{file-id}/content?download=1" \
  -H "Authorization: Bearer <token>" \
  -o downloaded-file.pdf
```

--------------------------------

### List Files and Folders

Source: https://context7.com/tgdrive/teldrive/llms.txt

Retrieve a list of files and folders. Supports filtering by path, category, search query, and pagination.

```APIDOC
## GET /api/files

### Description
Retrieves a list of files and folders from the specified path or based on search criteria.

### Method
GET

### Endpoint
/api/files

### Query Parameters
- **path** (string) - Optional - The path to list files from. Defaults to root '/'.
- **sort** (string) - Optional - The field to sort by (e.g., 'name').
- **order** (string) - Optional - The sort order ('asc' or 'desc').
- **limit** (integer) - Optional - The maximum number of items to return.
- **cursor** (string) - Optional - A token for paginating results.
- **query** (string) - Optional - A search query string.
- **searchType** (string) - Optional - The type of search (e.g., 'text').
- **deepSearch** (boolean) - Optional - Whether to perform a deep search.
- **category** (string) - Optional - Comma-separated list of categories to filter by.

### Response
#### Success Response (200)
- **items** (array) - List of file and folder objects.
  - **id** (string) - Unique identifier.
  - **name** (string) - Name of the file or folder.
  - **type** (string) - Type of item ('file' or 'folder').
  - **mimeType** (string) - MIME type of the file.
  - **size** (integer) - Size of the file in bytes.
  - **category** (string) - Category of the file.
  - **encrypted** (boolean) - Whether the file is encrypted.
  - **updatedAt** (string) - Timestamp of the last update.
- **meta** (object) - Metadata for pagination.
  - **nextCursor** (string) - Token for the next page of results.

### Response Example
```json
{
  "items": [
    {
      "id": "file-uuid",
      "name": "document.pdf",
      "type": "file",
      "mimeType": "application/pdf",
      "size": 1048576,
      "category": "document",
      "encrypted": false,
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "nextCursor": "cursor-for-next-page"
  }
}
```
```

--------------------------------

### Troubleshooting Docker Logs

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/guides/caddy-cloudflare.md

Commands to view logs for Caddy and Teldrive containers to diagnose issues.

```sh
docker logs <caddy-container>
docker logs <teldrive-container>
```

--------------------------------

### Docker Compose for Teldrive, Caddy, and Imgproxy

Source: https://github.com/tgdrive/teldrive/blob/main/docs/docs/guides/caddy-cloudflare.md

Defines services for Teldrive, Caddy, and imgproxy in a Docker Compose file. Ensure ports 80 and 443 are open and Cloudflare is configured for 'Full' or 'Full (strict)' SSL/TLS.

```yaml
services:
  teldrive:
    image: ghcr.io/tgdrive/teldrive
    restart: unless-stopped
    networks:
      - web
    volumes:
      - ./config.toml:/config.toml:ro

  caddy:
    image: caddy:2
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    networks:
      - web
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config

  imgproxy:
    image: darthsim/imgproxy
    restart: unless-stopped
    networks:
      - web
    environment:
      IMGPROXY_ALLOW_ORIGIN: "*"
      IMGPROXY_ENFORCE_WEBP: true

networks:
  web:
    external: true

volumes:
  caddy_data:
  caddy_config:
```

--------------------------------

### Run TelDrive Application

Source: https://github.com/tgdrive/teldrive/blob/main/CONTRIBUTING.md

Runs the TelDrive application after it has been built. Requires a successful build.

```bash
task run
```

--------------------------------

### Clone TelDrive Repository

Source: https://github.com/tgdrive/teldrive/blob/main/CONTRIBUTING.md

Clones the TelDrive repository and navigates into the project directory. Requires Git.

```bash
git clone https://github.com/tgdrive/teldrive.git
cd teldrive
```