استفاده از CLIهای تولیدشده در Postman

استفاده از CLI تولیدشده

CLI تولیدشده توسط Postman یک ابزار خط فرمان بر پایه Go است که روی Go SDK تولیدشده قرار می‌گیرد و عملیات API را از terminal در اختیار شما می‌گذارد. این راهنما نصب، احراز هویت، تنظیمات، اجرای commandها و استفاده از skillهای AI agent را توضیح می‌دهد.

پیش‌نیاز

برای build کردن CLI، باید Go روی سیستم نصب باشد.

فایل go.mod پروژه را بررسی کنید تا حداقل نسخه Go مورد نیاز را ببینید.
Go را از سایت رسمی Go نصب کنید.
نصب را بررسی کنید:

go version

نمونه خروجی:

go version go1.20.5 darwin/amd64

نصب و build

بعد از دریافت کد CLI، از ریشه پروژه این دستورها را اجرا کنید:

go mod tidy
go build .

یک فایل اجرایی در همان پوشه ساخته می‌شود. نام واقعی CLI را جایگزین <cli-name> کنید:

./<cli-name> --help

برای اینکه CLI از هر مسیر سیستم قابل اجرا باشد، binary را به یکی از مسیرهای PATH منتقل کنید:

mv ./<cli-name> /usr/local/bin/<cli-name>

بعد از آن می‌توانید از هر پوشه‌ای اجرا کنید:

<cli-name> --help

Help برای commandها

همه commandها و subcommandها از flag --help پشتیبانی می‌کنند:

# Help سطح اصلی
<cli-name> --help

# Help برای یک گروه command
<cli-name> <command-group> --help

# Help برای یک command مشخص
<cli-name> <command-group> <command> --help

احراز هویت

اگر API شما به احراز هویت نیاز دارد، CLI یک command به نام setup-auth می‌سازد. برای دیدن روش‌های پشتیبانی‌شده:

<cli-name> setup-auth --help

ذخیره اطلاعات ورود

اطلاعات احراز هویت در یک فایل JSON محلی ذخیره می‌شود:

~/.cli-name/credentials

در این مسیر، cli-name نام binary تولیدشده است؛ مثلا ~/.my-api/credentials.

پوشه با permission 0700 ساخته می‌شود.
فایل credentials با permission 0600 نوشته می‌شود.
credentials بین sessionها باقی می‌ماند؛ فقط وقتی اطلاعات تغییر کرد دوباره setup-auth را اجرا کنید.

Basic authentication

برای تنظیم username و password:

<cli-name> setup-auth basic <username> [password]

اگر password را وارد نکنید، CLI آن را به شکل امن از شما می‌پرسد:

<cli-name> setup-auth basic my-user
# Password: ********
# Basic authentication credentials saved successfully.

API key authentication

برای تنظیم API key:

<cli-name> setup-auth api-key [value]

اگر مقدار را ندهید، CLI آن را به شکل امن دریافت می‌کند:

<cli-name> setup-auth api-key
# API Key: ********
# API key authentication credentials saved successfully.

OAuth authentication

OAuth از زیرگروه setup-auth oauth مدیریت می‌شود:

<cli-name> setup-auth oauth --help

Client credentials flow

برای احراز هویت machine-to-machine با OAuth ۲.۰ Client Credentials:

<cli-name> setup-auth oauth client-credentials \
  --client-id "your-client-id" \
  --client-secret "your-client-secret"

client ID و client secret در credentials ذخیره می‌شوند و برای درخواست‌های بعدی استفاده خواهند شد.

Authorization code flow

برای ورود تعاملی کاربر با Authorization Code:

<cli-name> setup-auth oauth authorization-code [flags]

CLI یک server محلی موقت روی http://127.0.0.1:<port>/callback اجرا می‌کند، browser را باز می‌کند، کاربر مجوز می‌دهد، و سپس access token و refresh token ذخیره می‌شوند. پورت پیش‌فرض معمولا 8777 است.

<cli-name> setup-auth oauth client-credentials \
  --client-id "abc123" \
  --client-secret "secret456"

<cli-name> setup-auth oauth authorization-code --scopes "read,write"

Configuration

با command config می‌توانید تنظیماتی مثل base URL را مدیریت کنید:

<cli-name> config --help

مقادیر تنظیمات با این اولویت خوانده می‌شوند:

Environment variables: با prefix نام CLI به شکل uppercase و جایگزینی hyphen با underscore. مثلا برای my-api، prefix برابر MY_API_ است.
Config file: فایل ./config/config.yaml نسبت به مسیری که CLI را از آن اجرا می‌کنید.
Built-in defaults: مقدارهای پیش‌فرض داخل SDK تولیدشده.

`config set`

برای تنظیم یک مقدار در config file:

<cli-name> config set base_url https://api.staging.example.com

`config get`

برای خواندن یک مقدار:

<cli-name> config get base_url
# base_url = https://api.staging.example.com

`config list`

برای نمایش همه مقدارهای فعلی:

<cli-name> config list
# base_url = https://api.staging.example.com

`config edit`

برای باز کردن config file در editor پیش‌فرض:

export EDITOR=vim
<cli-name> config edit

Environment variableها

نام CLI	کلید config	متغیر محیطی
`my-api`	`base_url`	`MY_API_BASE_URL`
`petstore-cli`	`base_url`	`PETSTORE_CLI_BASE_URL`

ساختار commandها

CLI ساختار سلسله‌مراتبی دارد:

<cli-name> <command-group> <command> [flags]

گروه command معمولا معادل سرویس یا دسته منبع API است؛ مثل users، projects یا billing. هر command هم یک عملیات API است؛ مثل list، get، create یا delete.

my-api users list
my-api users get --id "user-123"
my-api projects create --name "My Project" --body '{"description": "A new project"}'

Flagها و parameterها

parameterهای path، query و header به flag تبدیل می‌شوند. اگر flag اجباری را وارد نکنید، CLI خطا می‌دهد.

نوع	نمونه
String	`--name "John"`
Integer	`--page 1`
Float	`--threshold 0.95`
Boolean	`--verbose`
String Array	`--tags "a" --tags "b"`

Request body

برای عملیات‌هایی مثل POST، PUT و PATCH که body دارند، از --body یا --body-file استفاده کنید:

my-api users create --body '{"name": "Alice", "email": "alice@example.com"}'
my-api users create --body-file ./user.json

این دو flag با هم قابل استفاده نیستند. برای دیدن schema مورد انتظار، روی همان command از --help استفاده کنید.

Output

پاسخ commandها به صورت JSON خوانا در stdout چاپ می‌شود، و warningها یا errorها در stderr می‌آیند. به همین دلیل می‌توانید خروجی را به ابزارهای دیگر pipe کنید:

my-api users list | jq '.[].name'
my-api users get --id "user-123" > user.json

AI agent skills

کنار کد CLI، generator یک پوشه skills/ تولید می‌کند. این پوشه شامل فایل‌های Markdown است که برای AI agentهایی مثل Cursor، Copilot یا workflowهای LLM سفارشی قابل خواندن هستند.

هر skill معمولا در مسیر skills/<group>-<command>/SKILL.md قرار دارد و بخش‌هایی مثل frontmatter، overview، usage، example، جدول flagها، request body و مثال‌های بیشتر را شامل می‌شود.

این skillها به agent کمک می‌کنند بدون حدس‌زدن، command درست را با flagهای لازم بسازد.

نام CLI

نام binary تولیدشده از تنظیمات SDK به دست می‌آید:

اگر goModuleName تنظیم شده باشد، آخرین بخش مسیر به عنوان نام CLI استفاده می‌شود؛ مثلا github.com/my-org/my-api-cli به my-api-cli تبدیل می‌شود.
اگر فقط sdkName وجود داشته باشد، به kebab-case تبدیل می‌شود؛ مثلا MyCli به my-cli.
اگر هیچ‌کدام نباشد، نام پیش‌فرض go-cli است.

`sdkName`	`goModuleName`	نام binary	مسیر module
`MyCli`	تنظیم نشده	`my-cli`	`github.com/my-cli`
`PetStore`	`github.com/acme/petstore-cli`	`petstore-cli`	`github.com/acme/petstore-cli`
تنظیم نشده	تنظیم نشده	`go-cli`	`github.com/go-cli`

رفع اشکال

خطای `unknown config key`

کلید نامعتبر را با config set یا config get استفاده کرده‌اید. برای دیدن کلیدهای مجاز:

<cli-name> config --help

Credentials اعمال نمی‌شود

وجود فایل credentials و نام درست پوشه را بررسی کنید:

cat ~/.cli-name/credentials

نام پوشه باید با نام binary CLI هماهنگ باشد.

Config file پیدا نمی‌شود

فایل config از مسیر ./config/config.yaml نسبت به محل اجرای CLI خوانده می‌شود. اگر فقط می‌خواهید base URL را عوض کنید، می‌توانید از environment variable استفاده کنید:

MY_API_BASE_URL=https://api.example.com <cli-name> users list

OAuth authorization شکست می‌خورد

اگر browser خودکار باز نشد، URL چاپ‌شده در stderr را دستی باز کنید. همچنین مطمئن شوید redirect URI زیر در تنظیمات OAuth app ثبت شده است:

http://127.0.0.1:<port>/callback

تداخل پورت در OAuth

اگر پورت 8777 اشغال است، پورت دیگری مشخص کنید:

<cli-name> setup-auth oauth authorization-code --port 9999

redirect URI در OAuth app را هم با همین پورت هماهنگ کنید.

منبع آموزشی: Postman Docs، بازنویسی و ساده‌سازی‌شده برای کاربران فارسی‌زبان.