Apidog CLI: Klien API Berbasis Terminal

Ruang kerja API Anda berada di GUI, tetapi hari kerja Anda sering berlangsung di terminal. Setiap perpindahan konteks memakan waktu dan fokus. Dalam pipeline CI atau sesi agen AI, GUI bahkan bukan opsi. Apidog CLI menutup celah ini dengan membawa platform Apidog—pengujian, endpoint, skema, lingkungan, ekspektasi mock, dan dokumentasi—ke shell prompt yang sudah Anda gunakan.

Coba Apidog hari ini

Apidog CLI bukan pengganti curl. Untuk satu GET ad-hoc dan melihat JSON, curl atau HTTPie sudah tepat. Jika Anda membutuhkan antarmuka interaktif, lihat rangkuman terminal dan klien REST TUI. Apidog CLI dirancang untuk bekerja dengan ruang kerja API Anda: menjalankan skenario pengujian yang sudah dibuat, membaca atau memperbarui kontrak API, serta mengimpor dan mengekspor spesifikasi melalui perintah yang bisa dipanggil dari skrip atau agen.

Apa arti “ada di terminal Anda”

Alat HTTP terminal biasanya menangani satu permintaan dalam satu waktu. Apidog CLI bekerja pada tingkat proyek. Lebih dari empat puluh grup perintahnya dapat dikelompokkan ke dalam lima tugas berikut.

Tugas	Perintah
Jalankan pengujian	run, test-scenario, test-suite, test-case, test-data, test-report
Kelola kontrak	endpoint, schema, folder, common-parameter, response-component, security-scheme
Kelola dokumentasi dan mock	doc, docs-site, shared-doc, mock
Konfigurasi dan koneksi	environment, variables, vault, database-connection, websocket, socketio
Operasi tim	branch, merge-request, runner, scheduled-task, audit-log, import, export

Mulai eksplorasi dari bantuan bawaan:

apidog --help
apidog endpoint --help
apidog run --help

Setiap perintah mendukung --help dan menghasilkan JSON terstruktur. Sebagian besar respons juga menyertakan agentHints.nextSteps, yang memberi petunjuk langkah berikutnya untuk Anda atau agen AI. Ini membantu CLI memandu alur kerja tanpa mengharuskan Anda menghafal semua perintah.

Instal dalam satu perintah

Apidog CLI tersedia sebagai paket npm apidog-cli dan berjalan di macOS, Linux, serta Windows. Anda memerlukan Node.js versi 16 atau lebih baru.

npm install -g apidog-cli
apidog --version

Selanjutnya, login dengan token akses API. Di aplikasi Apidog, klik avatar Anda, buka Pengaturan Akun, lalu salin token pada bagian Token Akses API.

apidog login --with-token <YOUR_TOKEN>

Token disimpan di ~/.apidog/config.toml. Jangan masukkan file tersebut ke repositori atau log build. Untuk CI, gunakan rahasia CI dan kirim token pada setiap eksekusi:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <scenario_id> \
  -e <env_id> \
  -r cli

Flag global yang paling sering digunakan:

Flag	Fungsi
--project	Memilih proyek Apidog
--branch	Memilih cabang proyek
--access-token	Menimpa token login yang tersimpan
--api-base-url	Mengarahkan CLI ke deployment Apidog yang di-hosting sendiri

Untuk penggunaan token di pipeline, baca panduan autentikasi Apidog CLI.

Jalankan pengujian yang dibuat secara visual

Alur kerja utamanya sederhana:

1. Buat skenario pengujian di editor visual Apidog.
2. Rangkai permintaan, ekstrak variabel dari respons, lalu gunakan variabel itu pada langkah berikutnya.
3. Tambahkan assertion untuk status, header, atau body respons.
4. Salin perintah dari tab CI/CD pada skenario.
5. Jalankan skenario dari terminal atau CI.

# Salin perintah ini, termasuk ID, dari tab CI/CD skenario
apidog run -t <scenario_id> -e <env_id> -r cli

Perintah akan keluar dengan kode 0 jika semua assertion berhasil dan kode nonnol jika ada assertion gagal. Karena itu, Anda dapat langsung menjadikannya langkah pipeline:

- name: Jalankan API test
  run: apidog run -t ${{ secrets.APIDOG_SCENARIO_ID }} -e ${{ secrets.APIDOG_ENV_ID }} -r cli,junit

Ganti nilai -e untuk menjalankan skenario yang sama terhadap lingkungan development, staging, atau production.

Untuk pengujian berbasis data, berikan file CSV atau JSON agar skenario diulang untuk setiap baris data. Anda tidak perlu menduplikasi langkah pengujian. Lihat panduan pengujian berbasis data dan panduan REST API langkah demi langkah jika memulai dari nol.

Simpan hasil sebagai artefak CI

Apidog CLI mendukung empat format laporan:

• cli: hasil langkah demi langkah di terminal
• html: laporan HTML
• json: hasil terstruktur untuk pemrosesan lanjutan
• junit: format yang umum dipakai dashboard CI

Gunakan satu atau beberapa format sekaligus:

apidog run -t <scenario_id> -e <env_id> -r cli,junit

Laporan non-terminal disimpan di direktori apidog-reports/. Anda dapat mengunggah direktori tersebut sebagai artefak pipeline. Lihat contoh output di panduan laporan pengujian.

Untuk eksekusi yang tidak bergantung pada laptop, gunakan runner dan scheduled-task untuk mengelola runner yang di-hosting sendiri serta pengujian terjadwal. Keduanya mendukung alur yang sama seperti pengujian API terjadwal di Apidog.

Kelola kontrak API tanpa membuka aplikasi

CLI yang sama dapat membaca dan menulis definisi API di proyek Anda.

apidog endpoint list --project <project_id>
apidog schema get <schema_id>
apidog environment list
apidog mock list

Gunakan grup perintah yang sesuai untuk mengelola:

• endpoint dan folder API;
• skema data;
• environment dan variabel;
• skema keamanan;
• komponen respons yang dapat digunakan kembali;
• ekspektasi mock;
• dokumentasi yang dipublikasikan;
• endpoint WebSocket dan Socket.IO;
• konfigurasi database yang digunakan skenario pengujian.

Perintah mock mengelola ekspektasi mock: pasangan request dan response tetap yang dikembalikan server mock. Sementara itu, doc dan docs-site digunakan untuk mengelola dokumentasi yang dipublikasikan.

Impor dan ekspor spesifikasi

Apidog CLI mendukung OpenAPI 3.x, Swagger 2.0, dan koleksi Postman. Ini berguna saat melakukan migrasi atau menjadikan spesifikasi sebagai bagian dari otomasi.

# Impor spesifikasi ke proyek
apidog import openapi.json --project <project_id>

# Ekspor proyek sebagai OpenAPI
apidog export --format openapi

OpenAPI dan Swagger adalah spesifikasi yang distandardisasi dan didukung oleh sebagian besar toolchain API. Dengan CLI, Anda dapat menarik spesifikasi dari sistem lain, mendorongnya ke Apidog, dan melacak seluruh pertukaran dalam version control.

Dibangun untuk agen AI

Rilis CLI tahun 2026 menekankan penggunaan oleh agen pengkodean AI. Ada empat bagian yang mendukungnya.

1. Output terstruktur

Setiap perintah mengembalikan JSON yang dapat diurai agen. Field agentHints.nextSteps memberi tahu tindakan berikutnya, termasuk langkah pemulihan saat terjadi kesalahan.

2. Skema input yang dapat diperiksa

Gunakan cli-schema untuk melihat bentuk JSON yang diharapkan oleh perintah tulis dan memvalidasi payload sebelum mengubah proyek.

# Lihat skema yang tersedia
apidog cli-schema list

# Ambil skema untuk operasi tertentu
apidog cli-schema get <schema_id>

# Validasi payload sebelum create atau update
apidog cli-schema validate < payload.json

Pola aman untuk operasi tulis:

1. Ambil skema.
2. Buat payload JSON.
3. Validasi payload.
4. Jalankan create atau update.

Dengan urutan ini, payload yang salah dapat diketahui sebelum menyentuh proyek.

3. Skill yang dikemas

Perintah skill menyediakan pengetahuan operasional CLI dalam format yang dapat dimuat langsung oleh agen. Latar belakangnya dijelaskan dalam artikel mengapa kami membangun skill Apidog CLI.

Dalam pengukuran internal, agen yang bekerja melalui skema CLI menggunakan sekitar 30% lebih sedikit panggilan alat dan 25% lebih sedikit token dibandingkan agen yang menebak payload. Rinciannya tersedia dalam analisis ini.

4. Gerbang izin dan cabang AI

Secara default, penulisan yang berasal dari AI ke cabang diblokir sampai manusia mengaktifkan Izin Edit AI Eksternal. Pengaturan ini tersedia di Apidog 2.8.32 atau lebih baru, melalui:

Pengaturan Proyek → Pengaturan Fitur → Pengaturan Fitur AI

Alternatifnya, gunakan cabang AI. Agen dapat mengimpor resource yang dibutuhkan, membuat perubahan di cabang terisolasi, lalu mengembalikan hasilnya sebagai merge request untuk ditinjau. Cabang AI yang tidak digunakan akan otomatis diarsipkan setelah 24 jam, sehingga eksperimen tidak menumpuk.

Apa yang bukan Apidog CLI

Tiga batasan berikut penting saat memilih alat.

Bukan klien request interaktif

Apidog CLI tidak dirancang untuk mengetik POST ad-hoc lalu mencetak respons dengan format yang indah. Untuk kebutuhan tersebut, gunakan curl, HTTPie, atau klien TUI.

Bukan open source

Paket ini proprietary dan npm adalah satu-satunya saluran instalasi. Selain --help, penggunaan memerlukan akun Apidog. Tingkat gratis mencakup alur kerja yang dibahas di artikel ini, tetapi jika lisensi yang dapat diaudit adalah persyaratan utama, runner open-source merupakan pilihan yang lebih tepat.

Bukan alat mandiri berbasis file lokal

Skenario, endpoint, dan environment berada di proyek Apidog, bukan dalam file lokal. Konsekuensinya, CLI menjadi bagian terminal dari platform yang sama untuk desain, pengujian, mocking, dan dokumentasi.

Di mana Apidog CLI cocok di kotak alat terminal

Perbedaan utama dengan runner lain adalah tempat pengujian dibuat:

• Newman dan Postman CLI menjalankan koleksi yang dibuat di Postman.
• Hurl dan Bruno menjalankan pengujian yang dibuat sebagai file teks.
• Apidog CLI menjalankan skenario yang dibuat di editor visual Apidog, tempat kontrak, mock, dan dokumentasi juga disimpan.

Baca perbandingan Apidog CLI vs Newman atau rangkuman alat pengujian API berbasis terminal teratas untuk konteks lebih lanjut.

Pengaturan praktis untuk kebanyakan tim:

• gunakan curl atau xh untuk request cepat dan ad-hoc;
• gunakan apidog run untuk suite pengujian yang konsisten di CI;
• simpan laporan junit atau json sebagai artefak build;
• jalankan suite yang sama di environment berbeda melalui -e.

Untuk pipeline siap pakai, lihat panduan GitHub Actions.

FAQ

Apakah Apidog CLI gratis digunakan?

Ya. Paket diinstal gratis dari npm, dan tingkat gratis Apidog mencakup pembuatan skenario serta menjalankannya melalui CLI. Paket berbayar menambahkan fitur skala tim, bukan akses CLI dasar.

Apakah ini menggantikan curl atau HTTPie?

Tidak. curl dan HTTPie menangani request ad-hoc. Apidog CLI menjalankan skenario pengujian tersimpan dan mengelola resource proyek. Dalam praktiknya, kebanyakan developer menggunakan keduanya.

Bisakah berjalan sepenuhnya headless di CI?

Ya. Gunakan --access-token dari rahasia CI, jalankan apidog run dengan ID skenario, lalu gunakan kode keluar untuk menentukan status build. Tidak diperlukan aplikasi desktop pada runner.

Format apa yang dapat diimpor dan diekspor?

OpenAPI 3.x, Swagger 2.0, dan koleksi Postman, untuk migrasi masuk maupun integrasi keluar.

Bagaimana agen AI menggunakannya dengan aman?

Gunakan pola skema-validasi-tulis dan gerbang izin. cli-schema validate menangkap payload yang salah sebelum disimpan, sementara cabang AI menjaga edit agen tetap terisolasi sampai manusia menggabungkannya. Lihat implementasinya dalam cara menggunakan Apidog CLI di Claude Code.

Terminal adalah tempat pengujian sudah berjalan dan tempat agen Anda bekerja. Dengan Apidog CLI, Anda dapat menjalankan skenario, mengelola kontrak, dan menghasilkan laporan tanpa berpindah konteks ke GUI. Unduh Apidog, instal CLI dari npm, lalu jalankan satu skenario dari awal hingga akhir. Saat siap menggunakan perintah lain selain run, buka halaman Apidog CLI untuk referensi perintah lengkap.