رابط خط فرمان آریانت (CLI)

ابزار Arianet CLI (دستور arianet) کلاینت رسمی خط فرمان پلتفرم ابری آریانت است. این ابزار با API عمومی آریانت کار می‌کند و به شما اجازه می‌دهد از ترمینال یا اسکریپت، سرور سفارش بدهید، مدیریت و حذف کنید، کلیدهای SSH و فایروال‌ها را مدیریت کنید و موجودی و فاکتورها را ببینید.

نصب

فایل اجرایی مناسب سیستم خود را از صفحه انتشارها دانلود کنید، آن را اجرایی کنید و در PATH قرار دهید:

chmod +x arianet
sudo mv arianet /usr/local/bin/
arianet version

در ویندوز، فایل .zip را دانلود کنید، arianet.exe را بیرون بیاورید و پوشه آن را به PATH اضافه کنید.

برای ساخت از سورس (Go نسخه 1.22 یا بالاتر):

git clone https://github.com/ariaservice/arianet-cli.git
cd arianet-cli
go build -o arianet ./cmd/arianet
sudo mv arianet /usr/local/bin/

شروع سریع

در https://cloud.ariaservice.net/users/api-tokens یک توکن API بسازید و دسترسی‌های (scope) لازم را به آن بدهید (بخش «دسترسی‌های توکن» پایین‌تر).

توکن را ذخیره کنید:

arianet configure --token <your-api-token>

بررسی کنید که کار می‌کند:
```
arianet auth whoami
```

سرور سفارش بدهید:

arianet region list                      # شناسه منطقه را انتخاب کنید
arianet plan list --region 1             # شناسه پلن را انتخاب کنید
arianet os list --region 1               # شناسه سیستم‌عامل را انتخاب کنید
arianet server create --plan 5 --region 1 --os 3 --hostname web-01

تنظیمات

تنظیمات در فایل config.yaml داخل پوشه تنظیمات کاربر ذخیره می‌شود (در لینوکس ~/.config/arianet/ و در macOS ~/Library/Application Support/arianet/). دستور arianet configure show مسیر دقیق و مقادیر فعال را نشان می‌دهد.

arianet configure                       # تنظیم تعاملی
arianet configure --token <token>       # ذخیره توکن
arianet configure --output json         # فرمت خروجی پیش‌فرض
arianet configure show                  # نمایش تنظیمات فعلی

اولویت از بالا به پایین: فلگ خط فرمان، متغیر محیطی، فایل تنظیمات.

متغیر محیطی	توضیح
`ARIANET_TOKEN`	توکن API
`ARIANET_API_URL`	آدرس پایه API (پیش‌فرض `https://api.ariaservice.net`)

فلگ‌های سراسری

فلگ	توضیح
`-o, --output`	`table` (پیش‌فرض) یا `json`
`--token`	توکن API فقط برای همین دستور
`--api-url`	آدرس پایه API فقط برای همین دستور

هر دستور فلگ --help دارد که فلگ‌ها را همراه با مثال نشان می‌دهد.

دسترسی‌های توکن

می‌توانید توکن را به دسترسی‌های مورد نیاز محدود کنید. اگر توکن دسترسی لازم را نداشته باشد، دستور با خطای INSUFFICIENT_SCOPE شکست می‌خورد.

دستورها	دسترسی
`region list`	`regions:read`
`os list`	`os:read`
`plan list`, `plan get`	`plans:read`
`server list/get/status/actions`	`servers:read`
`server create/delete/restart/power-*/reinstall/rename/toggle-protection`	`servers:write`
`balance`, `balance transactions`	`balance:read`
`balance invoices`	`invoices:read`
`ssh list/get` و `ssh add/update/delete`	`ssh-keys:read` و `ssh-keys:write`
`firewall list/get` و سایر دستورهای `firewall`	`firewalls:read` و `firewalls:write`

توکن را می‌توان به فهرستی از IPهای مبدأ هم محدود کرد؛ درخواست از آدرس دیگر با خطای IP_NOT_ALLOWED رد می‌شود.

دستورها

شناسه‌های --region، --plan، --os، --ssh-key و --server را از دستورهای list مربوط بگیرید.

احراز هویت

arianet auth whoami               # کاربر احراز هویت‌شده
arianet auth logout               # ابطال توکن فعلی و خروج
arianet auth tokens list          # فهرست توکن‌های API
arianet auth tokens revoke <id>   # ابطال یک توکن

کاتالوگ

arianet region list                     # مکان‌های قابل سفارش
arianet plan list --region <id>         # پلن‌های قابل سفارش در یک منطقه
arianet plan get <id>                   # جزئیات و قیمت پلن
arianet os list --region <id>           # سیستم‌عامل‌های موجود در یک منطقه

ستون ID در region list همان شناسه دیتاسنتر است. در همه جای دیگر آن را به‌عنوان --region بدهید.

سرورها

فهرست و مشاهده

arianet server list
arianet server list --status terminated
arianet server list --page 2 --limit 20
arianet server get <id>
arianet server status <id>
arianet server actions <id> --limit 50

بدون --status، سرورهای فعال و تعلیق‌شده نمایش داده می‌شوند. وضعیت‌های دیگر: creating، pending، failed، terminated، powering_on، powering_off، restarting و reinstalling_os.

server actions عملیات انجام‌شده روی سرور (ایجاد، ریستارت، نصب مجدد و ...) را از جدیدترین، همراه با نتیجه نشان می‌دهد.

ایجاد

arianet server create                                   # ویزارد تعاملی
arianet server create --plan 5 --region 1 --os 3 --hostname web-01
arianet server create --plan 5 --region 1 --os 3 --ssh-key 2
arianet server create --plan 5 --region 1 --os 3 --password '<root-password>'
arianet server create --plan 5 --region 1 --os 3 --no-wait --yes --output json

فلگ	توضیح
`--plan`	شناسه پلن
`--region`	شناسه منطقه (دیتاسنتر)
`--os`	شناسه سیستم‌عامل
`--hostname`	نام میزبان
`--ssh-key`	ورود با کلید SSH ذخیره‌شده به‌جای رمز عبور
`--password`	رمز root به انتخاب شما
`--currency`	شناسه ارز برای پرداخت (پیش‌فرض: کیف پول پیش‌فرض شما)
`--idempotency-key`	استفاده مجدد از یک کلید برای تکرار امن سفارش (توضیح پایین)
`--no-wait`	بلافاصله پس از پذیرش سفارش برگرد
`--timeout`	بیشترین زمان انتظار تا فعال شدن سرور (پیش‌فرض `15m`)
`-y, --yes`	رد کردن پرسش تأیید

اگر نه --ssh-key بدهید و نه --password، یک رمز root قوی تصادفی ساخته و فقط یک بار نمایش داده می‌شود. آن را ذخیره کنید؛ بعداً قابل نمایش نیست.
اگر --plan، --region یا --os را ندهید، ویزارد تعاملی آن‌ها را می‌پرسد. ویزارد ورودی تعاملی لازم دارد و با --output json رد می‌شود؛ در اسکریپت هر سه شناسه را بدهید.
به‌طور پیش‌فرض دستور تا فعال شدن سرور منتظر می‌ماند.

تکرار امن. هر سفارش یک کلید یکتایی (idempotency key) دارد. اگر بعد از ارسال سفارش شبکه قطع شود، اجرای دوباره همان دستور با همان --idempotency-key نتیجه سفارش قبلی را برمی‌گرداند و سرور دوم خریده نمی‌شود. وقتی CLI نتواند نتیجه را اعلام کند، کلید را چاپ می‌کند. خطاهای گذرای درگاه با همان کلید خودکار تکرار می‌شوند.

محدودیت نرخ. سرعت ایجاد سرور برای هر توکن و هر حساب محدود است. وقتی به محدودیت برسید، CLI می‌گوید چقدر باید صبر کنید.

عملیات

arianet server restart <id>   [--wait] [--timeout 15m] [--yes]
arianet server power-on <id>  [--wait]
arianet server power-off <id> [--wait] [--yes]
arianet server reinstall <id> --os <id> [--wait] [--yes]
arianet server delete <id>    [--wait] [--yes]
arianet server rename <id> --name <new-name>      # 1 تا 30 نویسه
arianet server toggle-protection <id> [--enable | --disable]

ریستارت، روشن/خاموش، نصب مجدد و حذف به‌محض پذیرش عملیات توسط پلتفرم برمی‌گردند. با --wait تا پایان عملیات منتظر می‌ماند: پیشرفت در stderr نوشته می‌شود و اگر عملیات شکست بخورد یا زمان تمام شود، کد خروج غیرصفر است. این دستورها هرگز خودکار تکرار نمی‌شوند، پس ریستارت اشتباهی دوباره انجام نمی‌شود.

toggle-protection با --enable یا --disable وضعیت را صریح تعیین می‌کند (تکرارش در اسکریپت بی‌خطر است). بدون این فلگ‌ها وضعیت فعلی برعکس می‌شود. سرور محافظت‌شده تا خاموش شدن محافظت نه حذف می‌شود و نه نصب مجدد.

کلیدهای SSH

arianet ssh list [--page 2 --limit 20]
arianet ssh get <id>
arianet ssh add --name laptop --key-file ~/.ssh/id_ed25519.pub --region <id>
arianet ssh add --name laptop --key "ssh-ed25519 AAAA..." --region <id>
arianet ssh update <id> --name <new-name>
arianet ssh delete <id> [--yes]

هر کلید SSH به یک منطقه تعلق دارد، پس هنگام افزودن --region الزامی است. هنگام سفارش با --ssh-key <id> از آن استفاده کنید.

فایروال‌ها

arianet firewall list
arianet firewall get <id>
arianet firewall create --name web-fw --region <id> [--description "..."]
arianet firewall update <id> [--name <name>] [--description "..."]
arianet firewall delete <id> [--yes]

arianet firewall rule add <id> --direction ingress --proto tcp --port 443 --remote-ip 0.0.0.0/0
arianet firewall rule add <id> --direction ingress --proto tcp --port 22 --remote-ip 203.0.113.7/32 --description office
arianet firewall rule add <id> --direction ingress --proto icmp --remote-ip 0.0.0.0/0
arianet firewall rule remove <id> <rule-id> [--yes]

arianet firewall attach <id> --server 42,43
arianet firewall detach <id> --server 42

فایروال جدید قانونی ندارد. قانون اضافه کنید و بعد آن را با attach به سرورها وصل کنید.
فلگ‌های rule add: ‏--direction ingress|egress (پیش‌فرض ingress)، --proto tcp|udp|icmp|esp|gre (پیش‌فرض tcp)، --port (پورت یا بازه مثل 8000-9000، برای tcp و udp الزامی)، --remote-ip (الزامی) و --description.
--remote-ip در قانون ورودی مبدأ مجاز و در قانون خروجی مقصد مجاز است. عمداً الزامی است: برای اجازه به همه 0.0.0.0/0 بدهید.
شناسه قانون در rule remove یک رشته است که در ستون Rule ID دستور firewall get دیده می‌شود. جایگاه قانون در فهرست نیست.
attach و detach در هر فراخوانی تا 50 سرور می‌پذیرند. --server را تکرار کنید یا شناسه‌ها را با کاما جدا کنید.

موجودی و فاکتورها

arianet balance                                  # موجودی کیف پول
arianet balance transactions [--page 2]
arianet balance invoices [--status paid] [--page 2 --limit 20]
arianet balance invoices get <number>            # یک فاکتور با ردیف‌هایش

فرمت خروجی

خروجی پیش‌فرض table برای انسان است. --output json داده API را برای اسکریپت‌ها به‌صورت JSON چاپ می‌کند:

arianet server list -o json | jq -r '.[] | select(.status == "active") | .id'
arianet server get 42 -o json | jq -r '.ip_addresses[0].ip'

با --output json:

stdout فقط نتیجه JSON را دارد. پیشرفت، خروجی انتظار و راهنماها در stderr نوشته می‌شوند.
پرسش‌های تأیید در stderr نوشته می‌شوند. در اسکریپت --yes بدهید تا منتظر ورودی نماند (server create در حالت JSON نمی‌پرسد).

خطاها در stderr به این شکل نوشته می‌شوند:

{"success":false,"error":{"code":"INSUFFICIENT_BALANCE","message":"...","status":402}}

کدهای خروج

کد	معنی
`0`	موفق
`1`	هر شکستی، از جمله `--wait` که شکست خورده، زمانش تمام شده یا ادامه نیافته

نمونه اسکریپت

سفارش سرور و ذخیره نتیجه:

out=$(arianet server create --plan 5 --region 1 --os 3 --hostname web-01 \
        --ssh-key 2 --yes --output json) || exit 1
id=$(echo "$out" | jq -r '.id')

تکرار امن پس از شکست، با کلیدی که خودتان تعیین می‌کنید:

key="order-$(date +%Y%m%d)-web-01"
until arianet server create --plan 5 --region 1 --os 3 --hostname web-01 \
        --ssh-key 2 --yes --idempotency-key "$key" --output json; do
  sleep 30
done

ریستارت همه سرورهای فعال و انتظار برای هرکدام:

for id in $(arianet server list -o json | jq -r '.[] | select(.status == "active") | .id'); do
  arianet server restart "$id" --yes --wait
done

عیب‌یابی

پیام / کد	علت و راه‌حل
`No API token configured`	`arianet configure --token <token>` را اجرا کنید یا `ARIANET_TOKEN` را تنظیم کنید.
`UNAUTHORIZED`	توکن اشتباه، ابطال‌شده یا منقضی است. `arianet configure show` را ببینید و توکن جدید بسازید.
`INSUFFICIENT_SCOPE`	توکن دسترسی لازم برای این دستور را ندارد. توکنی با آن دسترسی بسازید (جدول بالا).
`IP_NOT_ALLOWED`	توکن به IPهای مبدأ دیگری محدود است. از آدرس مجاز اجرا کنید یا توکن بدون این محدودیت بسازید.
`INSUFFICIENT_BALANCE`	کیف پول را شارژ کنید و دوباره تلاش کنید. `arianet balance` موجودی را نشان می‌دهد.
`NO_DEFAULT_WALLET`	کیف پول پیش‌فرض ندارید. `--currency <id>` را بدهید.
`RATE_LIMIT_EXCEEDED`	تعداد درخواست‌ها زیاد است. پیام می‌گوید چقدر صبر کنید.
`UPSTREAM_ERROR` / `UPSTREAM_UNAVAILABLE` / `WRITES_UNAVAILABLE`	پلتفرم موقتاً در دسترس نیست. صبر کنید و دوباره تلاش کنید. سفارش سرور را می‌توان با همان `--idempotency-key` تکرار کرد.
`VALIDATION_ERROR`	یکی از ورودی‌ها رد شده است. پیام نام فیلد را می‌گوید.

اگر server create بعد از ارسال سفارش قطع شد، پیش از سفارش دوباره arianet server list را ببینید، یا همان دستور را با --idempotency-key چاپ‌شده دوباره اجرا کنید.

پشتیبانی

مرجع API: API endpoints
داشبورد: https://cloud.ariaservice.net
گزارش مشکل: https://github.com/ariaservice/arianet-cli/issues

نصب​

شروع سریع​

تنظیمات​

فلگ‌های سراسری​

دسترسی‌های توکن​

دستورها​

احراز هویت​

کاتالوگ​

سرورها​

فهرست و مشاهده​

ایجاد​

عملیات​

کلیدهای SSH​

فایروال‌ها​

موجودی و فاکتورها​

فرمت خروجی​

کدهای خروج​

نمونه اسکریپت​

عیب‌یابی​

پشتیبانی​

نصب