# أوامر سطر الأوامر

توفر Trackio مجموعة شاملة من أوامر سطر الأوامل (CLI) التي تتيح لك الاستعلام عن معلومات المشاريع، والتشغيلات، والمقاييس، ومساحات HF دون الحاجة إلى تشغيل خادم MCP. تعمل الأوامر على البيانات المحلية افتراضيًا، أو على مساحة HF عن بُعد عند توفير `--space`. وهذا مفيد بشكل خاص لوكلاء LLM وسكربتات الأتمتة. ومع المخرجات المنظمة بصيغة JSON والوصول البرمجي إلى جميع بيانات التجارب، صُممت Trackio لدعم التجارب الآلية لتعلم الآلة التي تُشغَّل بواسطة LLMs.

## استعلام عن المساحات عن بُعد

تدعم جميع أوامر `list` و`get` و`query` التي تقرأ بيانات لوحة التحكم الاستعلام عن مساحة Hugging Face عن بُعد بدلاً من البيانات المحلية. مرّر علم `--space` مع معرّف مساحة أو عنوان URL كامل:

```sh
# Using a Space ID
trackio list projects --space username/my-space

# Using a Space URL
trackio list projects --space https://username-my-space.hf.space

# Works with any list/get/query command
trackio get metric --project "my-project" --run "my-run" --metric "loss" --space username/my-space
```

بالنسبة إلى مساحات (Spaces) خاصة، مرّر `--hf-token` أو تأكد من تسجيل الدخول عبر `huggingface-cli login`:

```sh
trackio list projects --space username/private-space --hf-token hf_xxxxx
```

> **ملاحظة:** لا تدعم الأوامر `show` و`status` و`sync` و`freeze` و`skills` و`registry` و`list spaces` الخيار `--space`. استخدم `trackio list spaces` للاطلاع على لوحات تحكم Trackio على Hugging Face Hub، ثم مرّر أحد معرّفات Space تلك إلى أوامر مثل `trackio list projects --space username/my-space`.

## أوامر السجل

أنشئ سجلاً (registry) و، عند الحاجة، عرّف مجموعة مُنمّطة (typed collection) قبل ربط العناصر بها:

```sh
trackio registry create models --description "Models we deploy"
trackio registry create-collection models/churn-model --type model --description "Churn predictor"
```

اربط إصدارًا لقطعة محلية، أو ترقِ إصدار مجموعة عن طريق نقل مستعار، أو ألغِ ربط إصدار:

```sh
trackio registry link models/churn-model experiments/resnet:v3 --alias staging
trackio registry promote models/churn-model production v0
trackio registry unlink models/churn-model v0
```

فحص المجموعات وسجل تدقيقها:

```sh
trackio registry list models
trackio registry show models/churn-model
trackio registry events models
```

تقبل جميع أوامر السجل `--bucket-id org/bucket` لسجل مدعوم بوعاء تخزين و`--json` لإخراج منظم. يمكن تكرار `--alias`. يمكن كتابة الأهداف إما على شكل `models/churn-model` أو `registry-models/churn-model`.

يحلل أمر `link` `project/artifact:version-or-alias` من بيانات Trackio المحلية؛ ويُستبعد لاحقة `latest` لحلّ `latest`. لا يزال نشر عنصر موجود فقط على Space عن بُعد يستخدم واجهة برمجة التطبيقات بلغة بايثون حتى تتمكن Trackio من تسجيل إحداثيات التخزين عن بُعد للمصدر.

## أمر المزامنة

رفع مشروع محلي إلى مساحة Hugging Face:

```sh
trackio sync --project "my-project" --space-id "username/space_id"
```

النشر كـ Space ثابت (يقرأ من حاوية HF Bucket، ولا يتطلب خادمًا):

```sh
trackio sync --project "my-project" --space-id "username/space_id" --sdk static
```

تقدّم مساحات Static البيانات مباشرةً من المتصفح، ولذلك تتطلب بيانات لقطة عامة. لا يُدعم `--sdk static --private`؛ استخدم Gradio SDK الافتراضي للوحات التحكم الخاصة.

مزامنة جميع المشاريع التي تحتوي على بيانات غير متزامنة مع مساحاتها (Spaces) المُهيّأة:

```sh
trackio sync --all
```

| علم | الوصف |
|------|-------------|
| `--project` | اسم المشروع المتزامن (مطلوب ما لم يتم استخدام `--all`) |
| `--space-id` | معرّف مساحة HF التي سيتم المزامنة معها (مثل `username/space_id`). إذا لم يتم تقديمه، يتم استخدام المساحة التي تم تكوينها مسبقًا |
| `--all` | مزامنة جميع المشاريع التي تحتوي على بيانات غير متزامنة |
| `--sdk` | `gradio` (الافتراضي) لخادم مباشر، أو `static` لمساحة تعتمد على دلو للقراءة فقط |
| `--private` | اجعل المساحة خاصة عند إنشاء مساحة Gradio جديدة. غير مدعوم مع `--sdk static` |
| `--force` | استبدال قاعدة البيانات الحالية دون طلب تأكيد |

## أمر التجميد

إنشاء لقطة ثابتة للقراءة فقط من مساحة Gradio نشطة:

```sh
trackio freeze --space-id "username/my-space" --project "my-project"
```

تحديد مساحة وجهة مخصصة:

```sh
trackio freeze --space-id "username/my-space" --project "my-project" --new-space-id "username/my-snapshot"
```

| علم | الوصف |
|------|-------------|
| `--space-id` | معرّف مساحة Gradio المصدر (مطلوب) |
| `--project` | المشروع الذي سيتم تجميده (مطلوب) |
| `--new-space-id` | معرّف مساحة (Space) الوجهة الثابتة. القيمة الافتراضية هي `{space_id}_static` |
| `--private` | غير مدعوم للصور الثابتة المجمّدة |

> **ملاحظة:** يجب أن يكون المصدر مساحة Gradio مع تثبيت حاوية عند `/data`. إذا كانت مساحة الوجهة موجودة مسبقًا وليست مساحة Trackio ثابتة، فسيرفض `freeze` تجاوزها. المساحة المجمّدة هي لقطة. المقاييس المتزامنة لاحقًا مع مساحة Gradio الأصلية لن تظهر في المساحة الثابتة المجمّدة ما لم تُشغّل `freeze` مرة أخرى. تتطلب اللقطات الثابتة المجمّدة بيانات وجهة عامة، لذا لا يُدعم `trackio freeze --private`.

### Bump

ترقية مساحة Trackio موجودة إلى إصدار Trackio المثبّت محليًا:

```sh
trackio bump username/my-space
```

`trackio bump --space username/my-space` يؤدي نفس الشيء.

تُوقف المساحة مؤقتًا أثناء ترقية، لذا تستمر مهام التدريب في تسجيل البيانات إلى صندوق الوارد الخاص بالمساحة. يتم نسخ قواعد بياناتها احتياطيًا إلى `trackio-backups/` في نفس الدلو، ويُحدَّث تثبيت Trackio الخاص بها، ثم تُعاد تشغيلها بحيث تنقل النسخة الجديدة البيانات. إذا فشلت المساحة المُحدَّثة في البدء أو أبلغت عن عدد صفوف أقل مما كان عليه سابقًا، يتم استعادة النسخة الاحتياطية وملفات المساحة السابقة.

لإبقاء المساحة الأصلية دون تغيير، انسخها مع دلوها إلى مساحة جديدة تعمل بالإصدار المحلي بدلاً من ذلك:

```sh
trackio bump username/my-space --new-space username/my-space-v2 --new-bucket username/my-space-v2-bucket
```

| علم | الوصف |
|------|-------------|
| `space_id` | مساحة Trackio التي تريد ترقية (مطلوبة، أو مررها باستخدام `--space`) |
| `--new-space` | أنشئ هذا المساحة من نسخة من `space_id` بدلاً من الترقية في الموقع |
| `--new-bucket` | الحاوية الخاصة بـ`--new-space`. القيمة الافتراضية هي `{new_space}-bucket` |

> **ملاحظة:** يدعم `bump` مساحات Gradio التي تعمل بإصدار Trackio 0.21.0 أو أحدث مع وجود دلو (bucket) مُثبَّت في `/data`، ولا يُجري أي ترقية عكسية (downgrade) للمساحة. كانت المساحات الأقدم تخزّن بياناتها في مجموعة بيانات Hugging Face بدلاً من الدلو.

## أوامر القائمة

### عرض جميع المشاريع

list_projects

```sh
trackio list projects
```

```json
{
  "translation": "الإخراج بتنسيق JSON:"
}
```

```sh
trackio list projects --json
```

### قائمة مساحات Trackio

list لوحات تحكم Trackio الخاصة بـ Spaces التي تملكها حسابك ومنظماتك على Hugging Face:

```sh
trackio list spaces
```

```json
{
  "translation": "الإخراج بتنسيق JSON:"
}
```

```sh
trackio list spaces --json
```

قائمة مساحات Trackio تحت نطاق مستخدم أو منظمة محددة:

```sh
trackio list spaces --author "username-or-org"
```

تقييد عدد المساحات المُعاد:

```sh
trackio list spaces --limit 10
```

بالنسبة إلى مساحات (Spaces) خاصة، مرّر `--hf-token` أو تأكد من تسجيل الدخول عبر `huggingface-cli login`.

### عرض قائمة التشغيلات لمشروع

list_runs

```sh
trackio list runs --project "my-project"
```

```json
{
  "translation": "الإخراج بتنسيق JSON:"
}
```

```sh
trackio list runs --project "my-project" --json
```

### قائمة مقاييس تشغيل

قائمة بجميع المقاييس التي يتم تتبعها في تشغيل محدد:

```sh
trackio list metrics --project "my-project" --run "my-run"
```

```json
{
  "translation": "الإخراج بتنسيق JSON:"
}
```

```sh
trackio list metrics --project "my-project" --run "my-run" --json
```

### قائمة مقاييس النظام لتشغيل

list جميع مقاييس النظام (مثل مقاييس GPU) لتشغيل محدد:

```sh
trackio list system-metrics --project "my-project" --run "my-run"
```

```json
{
  "translation": "الإخراج بتنسيق JSON:"
}
```

```sh
trackio list system-metrics --project "my-project" --run "my-run" --json
```

### قائمة التقارير

عرض تقارير Markdown في مشروع (عبر جميع التشغيلات):

```sh
trackio list reports --project "my-project"
```

قائمة تقارير Markdown لتشغيل محدد:

```sh
trackio list reports --project "my-project" --run "my-run"
```

```json
{
  "translation": "الإخراج بتنسيق JSON:"
}
```

```sh
trackio list reports --project "my-project" --run "my-run" --json
```

### قائمة التتبعات

قائمة [التتبعات](./traces) (جلسات الوكيل أو المحادثة) عبر جميع التشغيلات في المشروع:

```sh
trackio list traces --project "my-project"
```

تعرض كل صف حالة التتبع، زمن التأخير الفعلي، التكلفة، عدد العمليات، وطلب المستخدم الذي بدأه. قم بالتصفية حسب التشغيل أو الخطوة أو النص:

```sh
trackio list traces --project "my-project" --run "production"
trackio list traces --project "my-project" --step 12
trackio list traces --project "my-project" --search "rate limit"
```

تبحث المطابقة في محتوى الرسالة، وبيانات التتبع الوصفية، واسم كل نطاق ونوعه ونموده وحالته وخطؤه. تحكّم في الترتيب والتصفّح:

```sh
trackio list traces --project "my-project" --sort step_desc --limit 100 --offset 50
```

يقبل `--sort` القيم `request_time_desc` (الافتراضي)، و`request_time_asc`، و`step_asc`، و`step_desc`. عند إضافة `--json`، يتم تضمين ملخص `summary` لكل تتبّع.

## الحصول على الأوامر

### الحصول على التتبع

اعرض أثرًا واحدًا مع شجرة التنفيذ الكاملة الخاصة به:

```sh
trackio get trace --project "my-project" --trace-id "fe04ed264a8a4bd6afcf266b56d9297e"
```

```
Trace fe04ed264a8a4bd6afcf266b56d9297e
  Run:      production
  Totals:   error | 25.0s | $0.33 | 101338 in / 1804 out tokens | 21 operation(s)

Execution:
  answer-research-question [span]  25.0s
    generate-research-response [span]  23.7s
      acquire-sandbox [span]  914ms
      dispatch-model-request [span]  2.18s
        provider-request [generation]  2.18s  my-model  8347->239 tok  $0.03
      ERROR run-bash-command [tool]  168ms
        -> {"exit_code": 2, "stderr": "hf datasets list: error: unrecognized arguments: --full"}
```

يقبل `--trace-id` المعرّف المختصر الذي يطبعه `trackio list traces` أو المعرّف الكامل المخزّن. أضف `--json` للحصول على التتبع الكامل، بما في ذلك مدخلات ومخرجات الأجزاء.

### الحصول على ملخص التتبع

اجمع كل نطاق حسب اسم العملية لمعرفة أين تذهب زمن الاستجابة والرموز والتكلفة، وأي العمليات التي تفشل:

```sh
trackio get trace-summary --project "my-project"
```

```
operation                  | kind       | calls | errors | avg_ms  | max_ms  | input_tokens | output_tokens | cost_usd
provider-request           | generation | 205   | 0      | 3380.8  | 5535.0  | 2915829      | 63020         | 9.6928
run-bash-command           | tool       | 157   | 25     | 818.4   | 1548.0  | 0            | 0             | 0.0
acquire-sandbox            | span       | 48    | 0      | 2438.6  | 10615.0 | 0            | 0             | 0.0
```

يمكنك التقييد بتشغيل واحد باستخدام `--run`، أو إخراج صفوف قابلة للقراءة آليًا باستخدام `--json`. لأي شيء لا تغطيه عملية التجميع، استعلم مباشرةً عن جدول `traces` باستخدام [`trackio query project`](#query-command) — حيث أن `spans` عمود بصيغة JSON، لذا يعمل `json_each`.

### الحصول على ملخص المشروع

احصل على ملخص مفصّل لمشروع، بما في ذلك عدد التشغيلات والنشاط الأخير:

```sh
trackio get project --project "my-project"
```

```json
{
  "translation": "الإخراج بتنسيق JSON:"
}
```

```sh
trackio get project --project "my-project" --json
```

يتضمن الملخص:
- اسم المشروع
- عدد مرات التشغيل
- قائمة بجميع التشغيلات
- آخر نشاط (الخطوة القصوى عبر جميع التشغيلات)

### الحصول على ملخص التشغيل

احصل على ملخص مفصّل لتشغيل محدد، بما في ذلك المقاييس والإعدادات:

```sh
trackio get run --project "my-project" --run "my-run"
```

```json
{
  "translation": "الإخراج بتنسيق JSON:"
}
```

```sh
trackio get run --project "my-project" --run "my-run" --json
```

يتضمن الملخص:
- أسماء المشاريع والتشغيل
- عدد إدخالات السجل
- الخطوة الأخيرة
- قائمة بجميع المقاييس
- إعدادات التشغيل (باستثناء الحقول الداخلية)

### الحصول على قيم المقاييس

احصل على جميع القيم لمقياس محدد في تشغيل:

```sh
trackio get metric --project "my-project" --run "my-run" --metric "loss"
```

```json
{
  "translation": "الإخراج بتنسيق JSON:"
}
```

```sh
trackio get metric --project "my-project" --run "my-run" --metric "loss" --json
```

يشمل المخرجات:
- رقم الخطوة
- الطابع الزمني
- قيمة المقياس

#### التصفية حسب الخطوة أو الوقت

يمكنك تصفية قيم المقاييس إلى خطوة محددة أو نافذة زمنية حول خطوة/طابع زمني. وهذا مفيد لفحص المقاييس حول الوقت الذي صدر فيه تنبيه.

```sh
# Get metric at exactly step 200
trackio get metric --project "my-project" --run "my-run" --metric "loss" --step 200

# Get metrics in a window around step 200 (±10 steps, the default)
trackio get metric --project "my-project" --run "my-run" --metric "loss" --around 200

# Get metrics in a window around step 200 (±50 steps)
trackio get metric --project "my-project" --run "my-run" --metric "loss" --around 200 --window 50

# Get metrics within ±60 seconds of a timestamp
trackio get metric --project "my-project" --run "my-run" --metric "loss" --at-time "2025-06-01T12:05:30" --window 60
```

| علم | الوصف |
|------|-------------|
| `--step N` | إرجاع المقياس عند الخطوة N بالضبط |
| `--around N` | إرجاع المقاييس في نافذة حول الخطوة N |
| `--at-time T` | إرجاع المقاييس في نافذة زمنية حول طابع الوقت T وفق معيار ISO 8601 |
| `--window W` | حجم النافذة: ±خطوات لـ `--around`، ±ثوانٍ لـ `--at-time` (الافتراضي: 10) |

### الحصول على لقطة للمقاييس

احصل على **جميع** المقاييس عند خطوة أو طابع زمني أو حولهما في استدعاء واحد. هذه هي أسرع طريقة لوكيل لفهم حالة التشغيل عند نقطة محددة — على سبيل المثال، في اللحظة التي أطلق فيها تنبيه.

```sh
# All metrics at step 200
trackio get snapshot --project "my-project" --run "my-run" --step 200 --json

# All metrics in a window around step 200 (±5 steps)
trackio get snapshot --project "my-project" --run "my-run" --around 200 --window 5 --json

# All metrics within ±60 seconds of a timestamp
trackio get snapshot --project "my-project" --run "my-run" --at-time "2025-06-01T12:05:30" --window 60 --json
```

مثال على مخرجات JSON:

```json
{
  "project": "my-project",
  "run": "my-run",
  "around": 200,
  "window": 5,
  "metrics": {
    "loss": [
      {"step": 196, "timestamp": "2025-06-01T12:04:50", "value": 0.42},
      {"step": 200, "timestamp": "2025-06-01T12:05:30", "value": 0.45}
    ],
    "accuracy": [
      {"step": 196, "timestamp": "2025-06-01T12:04:50", "value": 0.88},
      {"step": 200, "timestamp": "2025-06-01T12:05:30", "value": 0.87}
    ],
    "lr": [
      {"step": 196, "timestamp": "2025-06-01T12:04:50", "value": 0.0001},
      {"step": 200, "timestamp": "2025-06-01T12:05:30", "value": 0.0001}
    ]
  }
}
```

### الحصول على قيم مقاييس النظام

احصل على قيم مقاييس النظام لتشغيل. إذا لم يتم تقديم اسم مقياس، تُعاد جميع مقاييس النظام:

```sh
# Get all system metrics
trackio get system-metric --project "my-project" --run "my-run"

# Get a specific system metric
trackio get system-metric --project "my-project" --run "my-run" --metric "gpu_utilization"
```

```json
{
  "translation": "الإخراج بتنسيق JSON:"
}
```

```sh
trackio get system-metric --project "my-project" --run "my-run" --metric "gpu_utilization" --json
```

### الحصول على محتوى التقرير

اطبع إدخالات تقرير Markdown لاسم تقرير محدد في تشغيل:

```sh
trackio get report --project "my-project" --run "my-run" --report "training_report"
```

```json
{
  "translation": "الإخراج بتنسيق JSON:"
}
```

```sh
trackio get report --project "my-project" --run "my-run" --report "training_report" --json
```

## أمر الاستعلام

استخدم `trackio query` عندما تحتاج إلى استعلام SQL للقراءة فقط شامل لا تغطيه أوامر `trackio list` أو `trackio get` بالفعل.

### تنفيذ استعلام على قاعدة بيانات المشروع

```sh
trackio query project --project "my-project" --sql "SELECT run_name, MAX(step) AS last_step FROM metrics GROUP BY run_name ORDER BY last_step DESC"
```

```json
{
  "translation": "الإخراج بتنسيق JSON:"
}
```

```sh
trackio query project --project "my-project" --sql "SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name" --json
```

استعلام عن مساحة عن بُعد:

```sh
trackio query project --project "my-project" --sql "SELECT COUNT(*) AS num_alerts FROM alerts" --space username/my-space --json
```

`trackio query` يدعم فقط استعلامات `SELECT` و`WITH` واستعلامات `PRAGMA` الآمنة للمخطط، والتي تكون للقراءة فقط.

أمثلة شائعة على فحص المخطط:

```sh
# Inspect table columns
trackio query project --project "my-project" --sql "PRAGMA table_info(metrics)"

# Inspect indexes
trackio query project --project "my-project" --sql "PRAGMA index_list(alerts)"

# List tables
trackio query project --project "my-project" --sql "SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name"
```

يتضمن الاستجابة ما يلي:

- `project`
- `query`
- `columns`
- `rows`
- `row_count`

للحصول على تخطيط SQLite و parquet الكامل، راجع [مخطط التخزين والاستعلامات المباشرة](./storage_schema).

## صيغ المخرجات

تدعم جميع أوامر `list` و`get` و`query` صيغتي مخرجات:

1. **قابلة للقراءة من قِبل الإنسان** (الافتراضي): نص منسّق مناسب لعرضه في الطرفية
2. **JSON** (مع علم `--json`): مخرجات JSON منظمة مناسبة للاستهلاك البرمجي

## معالجة الأخطاء

تشمل أوامر سطر الأوامر التحقق الشامل ومعالجة الأخطاء:

- إذا لم يكن هناك مشروع موجود، يتم عرض رسالة خطأ
- إذا لم يكن هناك تشغيل في المشروع، يتم عرض رسالة خطأ
- إذا لم يكن هناك مقياس موجود في تشغيل، يتم عرض رسالة خطأ
- إذا لم يكن هناك تقرير موجود في تشغيل، يتم عرض رسالة خطأ
- إذا لم تكن الاستعلامات للقراءة فقط، فإن سطر الأوامر ينهي العملية مع إظهار خطأ

تُكتب جميع الأخطاء إلى stderr وتخرج الأوامر برمز خروج غير صفري.

## مثال على سير عمل

إليك سير عمل نموذجي لاستكشاف بيانات Trackio الخاصة بك:

```sh
# 1. List all projects
trackio list projects

# 2. List runs in a project
trackio list runs --project "my-project"

# 3. Get project summary
trackio get project --project "my-project"

# 4. Get run summary
trackio get run --project "my-project" --run "my-run"

# 5. List metrics in the run
trackio list metrics --project "my-project" --run "my-run"

# 6. Get specific metric values
trackio get metric --project "my-project" --run "my-run" --metric "loss"

# 7. Get all metrics at a specific step (e.g. where an alert fired)
trackio get snapshot --project "my-project" --run "my-run" --step 200 --json

# 8. Get system metrics (if available)
trackio list system-metrics --project "my-project" --run "my-run"

# 9. List reports in a run
trackio list reports --project "my-project" --run "my-run"

# 10. Print report markdown in terminal
trackio get report --project "my-project" --run "my-run" --report "training_report"

# 11. Run a direct SQL query
trackio query project --project "my-project" --sql "SELECT run_name, MAX(step) AS last_step FROM metrics GROUP BY run_name"
```

### استعلام عن مساحة عن بُعد

يعمل نفس سير العمل مع مساحة عن بُعد — ما عليك سوى إضافة `--space`:

```sh
# List projects on a remote Space
trackio list projects --space username/my-space

# Get metric values from a remote Space
trackio get metric --project "my-project" --run "my-run" --metric "loss" --space username/my-space --json
```

## حالات الاستخدام

### وكلاء نماذج اللغة

تُعدّ أوامر سطر الأوامر هذه مفيدة بشكل خاص لوكلاء نماذج اللغة الكبيرة التي تحتاج إلى:
- اكتشف المشاريع والتشغيلات المتاحة
- استعلام قيم المقاييس برمجياً
- افحص المقاييس المحيطة بتنبيه باستخدام `get snapshot` أو `get metric --around`
- نفّذ SQL مباشرًا للحالات التي لا تغطيها الأوامر المهيكلة
- احصل على الملخصات دون الحاجة إلى تشغيل خادم
- تحليل مخرجات JSON منظمة لمعالجتها بشكل إضافي

### سكربتات الأتمتة

يمكنك استخدام هذه الأوامر في سكربتات shell وخطوط أتمتة:

```sh
#!/bin/bash
PROJECT="my-project"
RUN="my-run"

# Get the latest loss value
LATEST_LOSS=$(trackio get metric --project "$PROJECT" --run "$RUN" --metric "loss" --json | jq -r '.values[-1].value')
echo "Latest loss: $LATEST_LOSS"
```

### التكامل مع أدوات أخرى

يجعل تنسيق المخرجات بصيغة JSON من السهل التكامل مع أدوات أخرى:

```sh
# Pipe to jq for filtering
trackio list runs --project "my-project" --json | jq '.runs[] | select(startswith("train"))'

# Export to file
trackio get run --project "my-project" --run "my-run" --json > run_summary.json
```