مرجع دستورات·۴ دقیقه مطالعه
اسکریپت‌نویسی و عامل‌های هوش مصنوعی
هر دستور همکاری در zev را یک اسکریپت، یک کار CI یا یک عامل هوش مصنوعی می‌تواند به همان خوبی اجرا کند که یک انسان پشت صفحه‌کلید. قواعد زیر قراردادی است که این ابزارها می‌توانند به آن تکیه کنند.
## قرارداد
- **خروجی `--json` روی stdout می‌رود**، به‌صورت یک سند JSON واحد. هر چیزی که برای انسان است، یعنی پیشرفت کار، پرسش‌ها، هشدارها و خطاها، روی stderr می‌رود. پس گرفتن stdout فقط داده را می‌گیرد.
- **کد خروج `0` یعنی موفقیت و `1` یعنی شکست.** در صورت شکست، توضیح روی stderr است و stdout خالی است؛ بنابراین یک دستور ناموفق هرگز خروجی‌ای تولید نمی‌کند که با نتیجه اشتباه گرفته شود.
- **رنگ‌ها هرگز وارد خروجی گرفته‌شده نمی‌شوند.** هر وقت stderr ترمینال نباشد رنگ‌ها خودکار خاموش می‌شوند، و وقتی متغیر محیطی `NO_COLOR` تنظیم شده باشد همیشه خاموش‌اند.
```bash
if result=$(zev pr list --json 2>/dev/null); then
echo "$result"
else
echo "zev failed" >&2
fi
```
یک استثنای عمدی برای قاعده‌ی «stdout در صورت شکست خالی است» وجود دارد: درخواست ادغام pull requestی که قبلاً ادغام شده با کد `1` خارج می‌شود و یک خطای قابل‌خواندن برای ماشین چاپ می‌کند، تا ابزار بتواند این حالت را از یک شکست واقعی تشخیص دهد:
```json
{"error":"pull request is already merged","status":"merged"}
```
## ورود دستگاهی و MCP برای عامل‌های هوش مصنوعی
یک عامل هرگز نباید حساب جداگانه یا کلید شما را داشته باشد. اجازه دهید از طریق شما وارد شود:
```bash
zev login zaryn.xyz --device --client "Claude Code"
```
یک پیوند و یک کد چاپ می‌کند. پیوند را باز می‌کنید، کد را بررسی می‌کنید، تیک هر چیزی را که لازم ندارد برمی‌دارید و تأیید می‌کنید. سپس عامل توکن خودش را دارد: به نام خودش، محدود به دسترسی‌هایی که تأیید کرده‌اید، با اعتبار ۹۰ روز، فهرست‌شده در تنظیمات که می‌توانید لغوش کنید، و ثبت‌شده در گزارش ممیزی به نام خودش.
برای اینکه Zaryn را به‌صورت ابزار در اختیار عامل بگذارید، سرور MCP همراه zev را بیفزایید:
```bash
claude mcp add zaryn -- zev mcp # Claude Code
codex mcp add zaryn -- zev mcp # Codex
```
`zev mcp` ابزارهای `zaryn_*` را برای مخزن‌ها، فایل‌ها، تاریخچه، جست‌وجو، مسئله‌ها، درخواست‌های ادغام، CI و هشدارها ارائه می‌دهد. می‌تواند مسئله باز کند و نظر بگذارد (با `repo:write`)؛ ادغام، حذف و تغییر تنظیمات بر عهدهٔ انسان‌هاست. عامل‌ها می‌توانند ساخت حساب را برای یک فرد آغاز کنند (`zev login … --register <name> --email <address>`)، اما فقط خود آن فرد با کدی که به صندوقش می‌رسد می‌تواند آن را تمام کند. [Zaryn برای عامل‌های هوش مصنوعی](/agents) را ببینید.
## هرگز منتظر پرسش نمانید
یک دستور فقط اطلاعاتی را می‌پرسد که شما نداده‌اید، پس دادن همه‌چیز به‌صورت پرچم آن را کاملاً غیرتعاملی می‌کند:
- `zev issue --title <t> --desc <d>` بدون پرسش یک issue می‌سازد.
- `zev issue comment <n> --body <text>` بدون پرسش نظر می‌گذارد.
- `zev pr --yes` یک pull request با عنوان و توضیحات پیش‌نویس‌شده و مقصد `main` باز می‌کند؛ برای مقصد دیگر `--target <branch>` را اضافه کنید.
- `zev issue close <n> --yes` و `zev pr merge <n> --yes` از تأیید صرف‌نظر می‌کنند. با `--json` هم تأیید پرسیده نمی‌شود، چون یک پرسش جلسه‌ی غیرتعاملی را معطل می‌کند.
## اعتبارنامه بدون ورود
```bash
export ZEV_SERVER=zaryn.xyz
export ZEV_TOKEN=zev_pat_...
zev issue list --repo alice/project --json
```
`ZEV_SERVER` و `ZEV_TOKEN` بر ورود ذخیره‌شده اولویت دارند، و `--server` و `--token` بر هر دو. همراه با `--repo owner/name`، این امکان را می‌دهد که یک ابزار از هر پوشه‌ای و بدون هیچ checkout محلی روی هر مخزنی کار کند.
خواندن از مخزن‌های عمومی به‌صورت ناشناس موفق می‌شود، پس توکن نامعتبر فقط وقتی تشخیص داده می‌شود که دستوری نیاز به نوشتن داشته باشد: ساختن، نظر دادن، بستن یا ادغام، خطای HTTP 401 و کد خروج `1` برمی‌گرداند.
## شکل‌های JSON
**`zev issue list --json`**
```json
{"issues":[{"number":1,"title":"Login button misaligned","status":"open","author":"alice","created_at":"2026-09-22 23:38:51+03:30"}]}
```
**`zev issue view <n> --json`** خود issue و رشته‌ی نظرهایش را با هم برمی‌گرداند:
```json
{"issue":{"number":1,"title":"...","description":"...","status":"open","author":"alice","created_at":"..."},
"comments":{"comments":[{"id":7,"author":"alice","body":"...","created_at":"..."}]}}
```
**`zev pr list --json`**
```json
{"pull_requests":[{"number":1,"title":"Add notes on the fix","source_branch":"fix-login-button","target_branch":"main","status":"open","author":"alice","created_at":"..."}]}
```
`zev pr view <n> --json` یک pull request را با همین فیلدها به‌علاوه‌ی `description` برمی‌گرداند.
**`zev status --json`**
```json
{"branch":"main","staged":[],"modified":["a.py"],"deleted":[],"untracked":["notes.txt"]}
```
وقتی HEAD جدا (detached) باشد، `branch` برابر `null` است.
## مثال: باز کردن pull request و گرفتن شماره‌ی آن
```bash
zev add .
zev commit "Automated change"
zev push
number=$(zev pr --yes --json 2>/dev/null | python3 -c "import json,sys; print(json.load(sys.stdin)['number'])")
echo "Opened pull request #$number"
```
## مثال: نظر گذاشتن روی همه‌ی issueهای باز
```bash
zev issue list --json 2>/dev/null \
| python3 -c "import json,sys; [print(i['number']) for i in json.load(sys.stdin)['issues'] if i['status']=='open']" \
| while read n; do
zev issue comment "$n" --body "Triaged automatically." --json > /dev/null
done
```
## بررسی درخت کاری پیش از اقدام
```bash
dirty=$(zev status --json | python3 -c "import json,sys; d=json.load(sys.stdin); print(len(d['staged'])+len(d['modified'])+len(d['deleted']))")
if [ "$dirty" != "0" ]; then
echo "Uncommitted changes present; not switching branches." >&2
exit 1
fi
zev checkout release
```
`zev checkout` خودش همین بررسی ایمنی را انجام می‌دهد و به‌جای بازنویسی هر چیزی با کد `1` خارج می‌شود؛ پس بررسی صریح بالا فقط وقتی لازم است که ابزار بخواهد پیش از تلاش تصمیم بگیرد چه کند.