Довідник CLI
Довідник командного рядка
Повний довідник для всіх команд, прапорців та параметрів конфігурації Godwit Sync.
Глобальні прапорці
Ці прапорці застосовуються до всіх команд.
| Прапорець | Тип | За замовч. | Ключ конфігурації | Опис |
|---|---|---|---|---|
| --lang | string | en-US | — | Мова для довідки та виводу консолі (напр. en-US, ua-UA) |
Базове використання
godwit sync --source <source> --destination <destination> [flags]Перевірка версії
godwit versionОтримання довідки
Ви можете використовувати команду help з будь-якою командою Godwit, щоб побачити повний опис використання, доступні прапорці та приклади. Використовуйте godwit help <команда> або godwit <команда> --help.
# Show general help
godwit help
# Show help for a specific command
godwit help sync
godwit help plan
# Use --help flag on any command
godwit sync --help
godwit plan list --helpДетальний режим
Увімкніть детальний режим з --ui для отримання детальної інформації про прогрес у реальному часі. Це відображає статистику передачі, прогрес по файлах, приблизний час завершення та інформацію про ліцензію.
godwit sync \
--source ./data \
--destination s3://my-bucket/backup \
--ui
Основні прапорці
Ці прапорці контролюють поведінку синхронізації.
| Прапорець | Тип | За замовч. | Ключ конфігурації | Опис |
|---|---|---|---|---|
| --config, -f | string | none | — | Шлях до YAML файлу конфігурації |
| --run-id | string | auto-generated | run.run_id | Ідентифікатор запуску для відстеження та відновлення передач |
| --source | string | required | source.url | Endpoint джерела (локальний шлях або s3://bucket/prefix) |
| --destination | string | required | destination.url | Endpoint призначення (локальний шлях або s3://bucket/prefix) |
| --plan-only | bool | false | — | Створити план синхронізації без копіювання даних |
| --resume | bool | false | — | Відновити раніше заплановану передачу |
| --parallel | int | 4 | options.parallel | Кількість паралельних воркерів синхронізації |
| --plan-parallel | int | 8 | options.plan_parallel | Кількість паралельних воркерів планування |
| --buffer-multiplier | int | 4 | options.buffer_multiplier | Множник довжини черги копіювання |
| --compare-policy | string | size,etag | policy.compare | Політика порівняння (size,etag або size,mtime) |
| --multipart-threshold | int | 67108864 | options.multipart_threshold | Розмір у байтах, що запускає multipart завантаження (64MB) |
| --rps | float | 0 (disabled) | rate_limit.rps | Ліміт запитів на секунду |
| --read-bps | int | 0 (disabled) | rate_limit.read_bps | Ліміт байтів читання на секунду |
| --max-inflight | int | 0 (disabled) | rate_limit.max_inflight | Максимум одночасних завантажень |
| --retry | int | 0 (disabled) | options.retry | Максимум повторів на обʼєкт перед визнанням помилки (0 = без повторів) |
| --retry-backoff | duration | 1s | options.retry_backoff | Базова затримка між повторами; зростає експоненційно (напр. 1s, 2s, 4s, …) |
| --override | bool | false | options.override | Перезаписати існуючі обʼєкти у призначенні (S3) |
| --skip | stringArray | none | policy.skip | Суфікси або regex для пропуску (напр., --skip .md5, --skip re:^logs/) |
| --match | string | none | policy.match | Включати лише ключі обʼєктів джерела, що відповідають регулярному виразу |
| --skip-tags | bool | false | options.skip_tags | Пропустити читання тегів обʼєктів з джерела (корисно, коли IAM не має дозволу s3:GetObjectTagging) |
| --unsupported-key-action | string | skip | options.unsupported_key_action | Дія при наявності символів у ключі обʼєкта, які не підтримуються призначенням (fail, skip, warn) |
| --version-mode | string | latest | versioning.mode | Режим списку версій (latest, all, since:<RFC3339>) |
| --object-lock | bool | false | object_lock.enabled | Реплікувати налаштування Object Lock (retention та legal hold) з джерела на призначення |
| --ram-conflict-check | bool | false | options.ram_conflict_check | Використовувати оперативну пам'ять для виявлення конфліктів регістру замість SQLite. Швидше планування, але необмежене споживання RAM пропорційно кількості унікальних ключів |
| --ui | bool | false | output.ui | Увімкнути детальне логування в консолі |
| --silent | bool | false | output.silent | Придушити весь вивід консолі |
| --brief | bool | false | output.brief | Показувати лише основні повідомлення прогресу (початок/завершення планування/завантаження) |
| --logs-dir | string | none | run.logs_dir | Директорія для логів спостережуваності |
| --status-addr | string | none | status.addr | HTTP-адреса для сервера статусу/метрик (напр., :8080) |
| --drain-timeout | int | 15 | status.drain_timeout | Секунди утримання сервера статусу/метрик активним після завершення операції, щоб Prometheus та інші читачі могли зібрати фінальні дані (потребує --status-addr) |
| --state-driver | string | sqlite | run.state_driver | Драйвер бекенду стану |
| --state-path | string | ./godwit-sync.state.db | run.state_path | Шлях до файлу БД стану |
Прапорці джерела S3
Налаштування підключення до джерела S3.
| Прапорець | Тип | За замовч. | Ключ конфігурації | Опис |
|---|---|---|---|---|
| --source-endpoint | string | required | source.endpoint | S3 API endpoint джерела |
| --source-auth | string | auto | source.auth_mode | Режим облікових даних джерела (static, env, profile, iam, assume-role, anonymous, auto) |
| --source-access-key | string | none | source.access_key | S3 ключ доступу джерела |
| --source-secret-key | string | none | source.secret_key | S3 секретний ключ джерела |
| --source-session-token | string | none | source.session_token | Необовʼязковий токен сесії для тимчасових облікових даних |
| --source-profile | string | none | source.profile | Імʼя AWS-профілю для джерела (використовується з --source-auth profile) |
| --source-role-arn | string | none | source.role_arn | IAM role ARN для STS AssumeRole джерела |
| --source-role-session | string | none | source.role_session | Імʼя сесії для STS AssumeRole джерела |
| --source-region | string | none | source.region | S3 регіон джерела |
| --source-secure | bool | true | source.secure | Використовувати TLS для S3 endpoint джерела |
| --source-disable-keepalive | bool | false | source.disable_keepalive | Вимкнути HTTP keep-alive для зʼєднань джерела |
Прапорці призначення S3
Налаштування підключення до призначення S3.
| Прапорець | Тип | За замовч. | Ключ конфігурації | Опис |
|---|---|---|---|---|
| --destination-endpoint | string | required | destination.endpoint | S3 API endpoint призначення |
| --destination-auth | string | auto | destination.auth_mode | Режим облікових даних призначення (static, env, profile, iam, assume-role, anonymous, auto) |
| --destination-access-key | string | none | destination.access_key | S3 ключ доступу призначення |
| --destination-secret-key | string | none | destination.secret_key | S3 секретний ключ призначення |
| --destination-session-token | string | none | destination.session_token | Необовʼязковий токен сесії для тимчасових облікових даних |
| --destination-profile | string | none | destination.profile | Імʼя AWS-профілю для призначення (використовується з --destination-auth profile) |
| --destination-role-arn | string | none | destination.role_arn | IAM role ARN для STS AssumeRole призначення |
| --destination-role-session | string | none | destination.role_session | Імʼя сесії для STS AssumeRole призначення |
| --destination-region | string | none | destination.region | S3 регіон призначення |
| --destination-secure | bool | true | destination.secure | Використовувати TLS для S3 endpoint призначення |
| --destination-disable-keepalive | bool | false | destination.disable_keepalive | Вимкнути HTTP keep-alive для зʼєднань призначення |
Прапорці ліцензії
Контроль поведінки ліцензування. Безкоштовний режим дозволяє планування до 10GB.
| Прапорець | Тип | За замовч. | Ключ конфігурації | Опис |
|---|---|---|---|---|
| --license-file | string | license.json | license.file | Шлях до файлу ліцензії (за замовчуванням: поруч з бінарним файлом) |
| --license | string | none | license.inline | Base64-рядок ліцензії в командному рядку |
| --register | string | none | — | Зареєструвати base64-ліцензію на диск |
Шаблони пропуску
Використовуйте --skip для виключення файлів за суфіксом або регулярним виразом.
# Skip by suffix
godwit sync --skip .md5 --skip .tmp ...
# Skip by regex pattern
godwit sync --skip "re:^logs/" --skip "re:\.bak$" ...
# Combine both
godwit sync --skip .md5 --skip "re:^temp/" ...Шаблони відповідності
Використовуйте --match для включення лише тих ключів об'єктів джерела, що відповідають регулярному виразу. Якщо встановлено, об'єкти, ключ яких не відповідає, виключаються з плану. Можна комбінувати з --skip для точної фільтрації.
# Only sync objects whose key matches a regex
godwit sync --match "^images/" ...
# Match a specific file extension
godwit sync --match "\.parquet$" ...
# Combine with --skip for fine-grained control
godwit sync --match "^data/" --skip .tmp ...Політика порівняння
Прапорець --compare-policy визначає, як порівнюються файли:
size,etagsize,etag — Порівняння розміру файлу та ETag (за замовчуванням, найкраще для S3)size,mtimesize,mtime — Порівняння розміру файлу та часу модифікації (для локальних файлових систем)
Управління планами
Godwit Sync відстежує кожен запуск синхронізації у базі даних стану. Використовуйте підкоманди plan для перегляду минулих запусків та їх прогресу.
plan list
Перегляд записаних запусків зі статусом, кількістю об'єктів, переданими байтами, тривалістю та помилками.
# List recent runs with stats
godwit plan list --state-path ./tmp/state.db
# Show last 10 runs
godwit plan list --limit 10
# Show only failed runs
godwit plan list --status failed
# Machine-readable output for scripts
godwit plan list --json| Прапорець | Тип | За замовч. | Ключ конфігурації | Опис |
|---|---|---|---|---|
| --config, -f | string | none | — | Шлях до YAML файлу конфігурації (використовуйте конфіг синхронізації для state_path, run_id тощо) |
| --limit | int | 30 | — | Максимальна кількість запусків для відображення |
| --status | string | none | — | Фільтрувати за статусом запуску (completed, failed, running, planned, pending) |
| --json | bool | false | — | Вивести як JSON масив замість таблиці |
| --state-driver | string | sqlite | run.state_driver | Драйвер бекенду стану |
| --state-path | string | ./godwit-sync.state.db | run.state_path | Шлях до файлу бази даних стану |
plan inspect
Детальний підсумок конкретного запуску — кількість об'єктів (всього, очікування, завершені, невдалі), обсяг переданих даних, розбивка за класами зберігання та повнота історії версій (повна, часткова, повністю пропущена).
godwit plan inspect --run-id <run-id> --state-path ./tmp/state.db
# Machine-readable JSON output
godwit plan inspect --json --run-id <run-id> --state-path ./tmp/state.db| Прапорець | Тип | За замовч. | Ключ конфігурації | Опис |
|---|---|---|---|---|
| --config, -f | string | none | — | Шлях до YAML файлу конфігурації (використовуйте конфіг синхронізації для state_path, run_id тощо) |
| --run-id | string | required | run.run_id | Ідентифікатор запуску для інспекції |
| --json | bool | false | — | Вивести як JSON обʼєкт з обʼєктами, даними, класами зберігання та проблемами |
| --state-driver | string | sqlite | run.state_driver | Драйвер бекенду стану |
| --state-path | string | ./godwit-sync.state.db | run.state_path | Шлях до файлу бази даних стану |
plan list objects
Перелік об'єктів для заданого запуску з фільтрацією за статусом. Доступні фільтри: all, pending, running, finished, skipped, failed, excluded, glacier, unsupported_key. Об'єднуйте кілька статусів через + (наприклад pending+running). Використовуйте --storage-class для додаткової фільтрації за класом зберігання S3. Використовуйте --partial-history для показу лише ключів з частковою історією версій.
# List all objects in a run
godwit plan list objects all --run-id <run-id> --state-path ./tmp/state.db
# List only running objects
godwit plan list objects running --run-id <run-id>
# Combine statuses with +
godwit plan list objects pending+running --run-id <run-id>
# Filter by storage class
godwit plan list objects all --storage-class GLACIER --run-id <run-id>
# List glacier-skipped objects
godwit plan list objects glacier --run-id <run-id>
# List keys with partial version history (mixed glacier/copied)
godwit plan list objects all --partial-history --run-id <run-id>
# List objects with case-conflicting keys (e.g. Photo.jpg vs photo.jpg)
godwit plan list objects all --case-conflict --run-id <run-id>
# List objects with keys unsupported on local filesystems
godwit plan list objects all --unsupported --run-id <run-id>
# Machine-readable JSON output
godwit plan list objects all --json --run-id <run-id>| Прапорець | Тип | За замовч. | Ключ конфігурації | Опис |
|---|---|---|---|---|
| --config, -f | string | none | — | Шлях до YAML файлу конфігурації (використовуйте конфіг синхронізації для state_path, run_id тощо) |
| --run-id | string | required | run.run_id | Ідентифікатор запуску |
| --storage-class | string | none | — | Фільтр за класом зберігання S3 (напр. STANDARD, GLACIER) |
| --json | bool | false | — | Вивести як JSON масив замість таблиці |
| --partial-history | bool | false | — | Показати лише ключі з частковою історією версій (змішані glacier/скопійовані версії) |
| --case-conflict | bool | false | — | Показати лише об'єкти з конфліктами регістру ключів (напр. Photo.jpg vs photo.jpg) |
| --unsupported | bool | false | — | Показати лише об'єкти з ключами, що містять символи, непідтримувані локальними файловими системами |
| --state-driver | string | sqlite | run.state_driver | Драйвер бекенду стану |
| --state-path | string | ./godwit-sync.state.db | run.state_path | Шлях до файлу бази даних стану |
plan verify
Верифікація завершених об'єктів шляхом порівняння їх MD5 контрольних сум з .md5 sidecar файлами у призначенні. Підтримує --resume для пропуску вже верифікованих об'єктів.
godwit plan verify --run-id <run-id> --destination s3://bucket/prefix --state-path ./tmp/state.db| Прапорець | Тип | За замовч. | Ключ конфігурації | Опис |
|---|---|---|---|---|
| --config, -f | string | none | — | Шлях до YAML файлу конфігурації |
| --run-id | string | required | run.run_id | Ідентифікатор запуску для верифікації |
| --resume | bool | false | — | Пропустити вже верифіковані обʼєкти та верифікувати решту |
| --destination | string | required | destination.url | Endpoint призначення (локальний шлях або s3://bucket/prefix) |
| --destination-endpoint | string | none | destination.endpoint | S3 API endpoint призначення |
| --destination-auth | string | auto | destination.auth_mode | Режим облікових даних призначення (static, env, profile, iam, assume-role, anonymous, auto) |
| --destination-access-key | string | none | destination.access_key | S3 ключ доступу призначення |
| --destination-secret-key | string | none | destination.secret_key | S3 секретний ключ призначення |
| --destination-session-token | string | none | destination.session_token | Необовʼязковий токен сесії для тимчасових облікових даних |
| --destination-profile | string | none | destination.profile | Імʼя AWS-профілю для призначення (використовується з --destination-auth profile) |
| --destination-role-arn | string | none | destination.role_arn | IAM role ARN для STS AssumeRole призначення |
| --destination-role-session | string | none | destination.role_session | Імʼя сесії для STS AssumeRole призначення |
| --destination-region | string | none | destination.region | S3 регіон призначення |
| --destination-secure | bool | true | destination.secure | Використовувати TLS для S3 endpoint призначення |
| --destination-disable-keepalive | bool | false | destination.disable_keepalive | Вимкнути HTTP keep-alive для S3 призначення |
| --parallel | int | 4 | options.parallel | Кількість паралельних воркерів верифікації |
| --rps | float | 0 (disabled) | rate_limit.rps | Ліміт запитів на секунду |
| --read-bps | int | 0 (disabled) | rate_limit.read_bps | Ліміт байтів читання на секунду |
| --max-inflight | int | 0 (disabled) | rate_limit.max_inflight | Максимум одночасних читань |
| --ui | bool | false | output.ui | Увімкнути детальне логування (показує результати по кожному обʼєкту) |
| --silent | bool | false | output.silent | Придушити весь вивід консолі |
| --brief | bool | false | output.brief | Показати лише початок та підсумок верифікації |
| --state-driver | string | sqlite | run.state_driver | Драйвер бекенду стану |
| --state-path | string | ./godwit-sync.state.db | run.state_path | Шлях до файлу бази даних стану |
| --logs-dir | string | none | run.logs_dir | Директорія для логів спостережуваності |
| --drain-timeout | int | 15 | status.drain_timeout | Секунди утримання сервера статусу/метрик активним після завершення верифікації, щоб Prometheus та інші читачі могли зібрати фінальні дані (потребує --status-addr) |
Довідник конфігураційного файлу
Віддаєте перевагу YAML конфігураційним файлам? Перегляньте повний довідник конфігураційного файлу з прикладами.
Переглянути довідник конфігурації