idoud CLI

Standalone Go CLI accelerated uploader for idoud.

Install / Update

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/mydearniko/idoud/main/install.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/mydearniko/idoud/main/install.ps1 | iex

Other systems

Build from source:

go build -o idoud .

Features

• Upload a single file:
  • idoud archive.zip
• Upload from stdin:
  • cat archive.zip | idoud --stdin --name archive.zip
• Full chunked upload flow:
  • sends PUT requests with Content-Range
  • uses X-Upload-Key across all chunks
  • retries retryable chunk failures (409/429/5xx/network)
  • waits for finalization via /v1/files/{id} readiness checks (with short server-side wait hints when supported)
• Optional upload password and download limit headers.

Build

cd cli
go build -o idoud .

Usage

idoud [flags] <file>
idoud --stdin [--name <filename> | <filename>] [flags]

Examples

idoud archive.zip
cat archive.zip | idoud --stdin archive.zip
idoud --server https://idoud.cc --parallel 16 archive.zip
idoud --password "secret" --download-limit 3 archive.zip

Important flags

• --server server origin, or comma-separated origins for per-chunk round-robin (default https://idoud.cc)
• --stdin read payload from stdin instead of a path argument
• --stdin-size known stdin size hint for stdin uploads
• --name upload filename override (recommended with --stdin)
• --chunk-size chunk size for Content-Range uploads (must be exactly 3145728 bytes / 3 MiB)
• --parallel parallel non-final chunk uploads (default 32)
• --subdomains force numbered upload subdomains 0..N-1 on idoud.cc origin
• --ips force chunk upload destination IPs (comma-separated), round-robin by chunk index
• --no-ipv6 disable IPv6 and force IPv4-only connections
• --no-subdomains disable numbered subdomain upload routing (alias: --nosub)
• --speedtest benchmark ingest path with server-side sink mode (no persisted file output)
• --retries retries per chunk (default 6)
• --hedge-delay speculative duplicate delay for slow non-final chunks (default 0s, disabled)
• --debug print live chunk concurrency, retries, throughput, and 7-sample moving average speed to stderr
• --request-timeout timeout for non-final chunk requests (default 45s)
• --final-request-timeout timeout for final chunk request (default 95s)
• --finalize-recovery-timeout readiness wait after uncertain final chunk responses (default 95s)
• --finalize-poll-interval readiness poll interval (default 1.2s)
• --finalize-timeout max wait for server finalization (default 20m)
• --output stdout mode: url (default), json, none
• --json shorthand for --output json
• --password sets X-Upload-Password
• --download-limit sets X-Upload-Download-Limit
• --insecure skip TLS verification
• --verbose enable retry/finalization logs to stderr

Notes

• Stdin uploads are streamed with bounded RAM using a chunk buffer pool.
• For unknown stdin size, the CLI still uploads in parallel using chunked Content-Range: bytes .../* requests and marks only the last chunk with X-Upload-Final: 1.
• --output url prints exactly one final URL to stdout on success.
• --output json prints exactly one JSON document to stdout for success, --help, and CLI errors.
• --output none prints nothing to stdout on success (i don't know why)
• --verbose and --debug never write to stdout; they only write diagnostics to stderr.

Automation Output Modes

--output url (default)

For successful uploads, stdout contains exactly one line:

https://idoud.cc/AbC123/file.bin

Errors stay on stderr.

--output none

For successful uploads, stdout is empty. Useful when the caller only cares about the exit code.

--output json / --json

Stdout contains exactly one JSON object and nothing else. This applies to:

• successful uploads
• --help
• CLI usage/argument errors
• input/open errors
• upload/runtime errors

JSON schema

Top-level fields:

• schema_version integer schema version, currently 1
• ok boolean success flag
• type one of result, help, error
• exit_code process exit code
• result present only when type=result
• help present only when type=help
• error present only when type=error

result fields:

• url final public URL
• name upload filename after CLI sanitization
• source file or stdin
• known_size whether the CLI knew the full input size before upload completion
• size total size in bytes when known

error fields:

• code stable machine code:
  • usage_error
  • input_error
  • upload_failed
• message human-readable error string
• hint optional human-readable recovery hint, currently used for usage errors

JSON examples

Success:

{
  "schema_version": 1,
  "ok": true,
  "type": "result",
  "exit_code": 0,
  "result": {
    "url": "https://idoud.cc/AbC123",
    "name": "archive.zip",
    "source": "file",
    "known_size": true,
    "size": 123456
  }
}

Usage error:

{
  "schema_version": 1,
  "ok": false,
  "type": "error",
  "exit_code": 2,
  "error": {
    "code": "usage_error",
    "message": "missing input: pass a file path or use --stdin",
    "hint": "pass a file path (idoud <file>) or use stdin mode (cat <file> | idoud --stdin --name <filename>)"
  }
}

Help:

{
  "schema_version": 1,
  "ok": true,
  "type": "help",
  "exit_code": 0,
  "help": {
    "text": "IDOUD CLI\n..."
  }
}