CLI kenari

@kenarihq/cli adalah wrapper resmi kenari untuk memakai model native dan model kenari dalam satu sesi Claude Code, Codex, atau Grok Build. Perintah claude, codex, dan grok biasa tetap memakai provider native. Routing kenari hanya aktif saat kamu menjalankan tool lewat wrapper.

Untuk mengarahkan semua sesi ke satu model kenari, atur tool-nya langsung: Claude Code memakai variabel environment dan Codex memakai file konfigurasinya. Lihat Claude Code atau Codex.

Prasyarat

CLI membutuhkan Node.js 18 atau lebih baru, dan tool yang ingin kamu jalankan harus sudah terpasang. CLI menjalankan tool itu dan tidak memasangnya. Cek Node.js:

node --version

Kalau Node.js belum ada, pasang dari nodejs.org atau lewat package manager, misalnya brew install node atau nvm install --lts.

Pasang

npm install -g @kenarihq/cli

kenari update memperbarui instalasi global. kenari update --check menampilkan versi terpasang dan versi terbaru tanpa memasang apa pun. Perintah ini menolak berjalan di checkout git.

kenari login

Perintah ini membuka halaman persetujuan kenari di browser. Klik Approve access, lalu CLI menerima API key baru lewat callback lokal di 127.0.0.1 dan menyimpannya di ~/.kenari/credentials.json. Key tidak pernah dicetak utuh. Callback ini membutuhkan browser di mesin yang sama dengan CLI, dan login kedaluwarsa setelah 5 menit.

Key baru muncul di API Keys pada dashboard. Kamu bisa mencabutnya kapan saja seperti key lain, dan request dengan key ini mengikuti penagihan yang sama dengan key lainmu. Key ini juga bisa membuat key terpisah untuk setiap tool. Lihat Key per tool.

Di server atau lewat SSH

Di server, container, atau sesi SSH tidak ada browser lokal. Buat key di halaman API Keys, lalu jalankan:

kenari login --api-key

Prompt menyembunyikan isi yang kamu tempel dan menampilkan satu * per karakter, jadi kamu tahu tempelannya masuk. Bila stdin bukan terminal, flag yang sama membaca key dari stdin, cocok untuk entrypoint atau langkah CI:

echo "$KENARI_KEY" | kenari login --api-key

Jangan pernah mengirim key sebagai argumen. kenari login --api-key kn-... ditolak, karena key di command line tersimpan di riwayat shell dan terlihat di ps oleh semua user di mesin itu.

Flag lama --no-browser, --paste, dan --stdin sudah dihapus. Pakai --api-key.

Bila home directory hanya bisa dibaca, seperti di banyak container, arahkan KENARI_HOME ke path yang bisa ditulis sebelum login:

export KENARI_HOME=/tmp/kenari
echo "$KENARI_KEY" | kenari login --api-key

kenari status --check

Baris credential menampilkan stored bila key tersimpan dan missing bila tidak. Dengan --check, perintah ini juga memeriksa jaringan dan mencetak satu baris check per target: router, native_anthropic, native_openai, native_xai, kenari, dan catalog. Masing-masing menampilkan ok atau failed beserta alasannya. Pengecekan kenari dan catalog memuat katalog model dengan key-mu. Hasilnya tidak membuktikan bahwa saldomu cukup untuk model berbayar. Perintah ini keluar dengan kode bukan nol bila ada pengecekan yang gagal. Tambahkan --json untuk output yang bisa dibaca mesin.

Atur role

kenari configure

Perintah ini menanyakan tool dan role mana yang akan memakai kenari. Jika lebih dari satu tool terpasang, kenari menanyakan mana yang diatur dan defaultnya semua. Jika hanya satu yang terpasang, kenari memilihnya otomatis. Di skrip, sebutkan toolnya: claude, codex, atau grok.

Setiap role tetap native atau memakai model tetap dengan nilai kenari/<model-id>:

Tool	Role
Claude Code	`main`, `opus`, `sonnet`, `haiku`, `fable`, `subagents`
Codex	`main`, `review`, `subagents`
Grok Build	`main`

native adalah default. Role native tetap memakai provider dan login bawaan tool, jadi masuk ke Claude Code, Codex, atau Grok seperti biasa. Di Codex, main juga menerima picker, yang menyerahkan pilihan model ke Codex, sedangkan review dan subagents menerima inherit, yang memakai model yang sama dengan sesi.

Subagents di Grok memakai model yang sama dengan sesi, jadi kenari menyalin main ke slot itu dan tidak menanyakannya. Request Grok yang dikirim ke kenari menyertakan web search kenari, sedangkan request yang tetap native memakai pencarian bawaan Grok. Jika semua role Grok memakai kenari, kenari login sudah cukup. Role Grok yang native tetap membutuhkan grok login atau XAI_API_KEY.

Konfigurasi non-interaktif membutuhkan --yes dan semua role tool itu. Grok hanya membutuhkan --main:

kenari configure claude \
  --main native \
  --opus native \
  --sonnet kenari/step-3-7-flash:free \
  --haiku native \
  --fable native \
  --subagents native \
  --yes

kenari configure codex \
  --main picker \
  --review inherit \
  --subagents kenari/step-3-7-flash:free \
  --yes

kenari configure grok \
  --main kenari/step-3-7-flash:free \
  --yes

Id model dengan awalan kenari/ selalu menuju kenari, dan wrapper tidak pernah melakukan fallback ke provider lain. Di Codex dan Grok, id tanpa awalan selalu tetap native. Di Claude Code, id tanpa awalan pada giliran utama tetap native, sedangkan alias opus, sonnet, haiku, fable, best, dan opusplan, serta request sampingan seperti compaction atau subagents, mengikuti slot kenari yang sesuai. Pilih id dari Model & harga, atau jalankan kenari models.

Reasoning effort per role

Role yang memakai model kenari bisa mengunci satu level reasoning, dan setiap request ke role itu memakainya. Tambahkan --<role>-effort, misalnya:

kenari configure claude \
  --main native \
  --opus native \
  --sonnet kenari/glm-5-2 --sonnet-effort max \
  --haiku native \
  --fable native \
  --subagents native \
  --yes

kenari configure interaktif menawarkan pilihan yang sama setelah kamu memilih model. Level yang dikunci mengalahkan level yang diminta sesi. kenari tidak memvalidasi level itu. Jika model tidak mendukungnya, gateway memakai level terdekat yang didukung, dan kenari status menampilkan kedua nilainya:

effort      kenari/glm-5-2 requested=max (pinned) gated=xhigh 200 4m ago

requested adalah level yang sampai ke gateway dan gated adalah level yang diterapkan. unset berarti tidak ada level yang dikirim, dan unreported berarti gateway tidak menyebutkannya.

Lihat rute aktif per role:

kenari status

Jalankan wrapper

kenari claude [args...]
kenari codex [args...]
kenari grok [args...]

Setiap peluncuran menyalakan router privat di port acak pada 127.0.0.1, menjalankan tool aslinya dengan pengaturan yang hanya berlaku untuk proses itu, meneruskan input terminal dan signal, lalu mematikan router saat tool selesai. Wrapper tidak menulis pengaturan provider atau credential ke konfigurasi Claude Code, Codex, maupun Grok.

Jika ~/.claude/settings.json masih berisi ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, atau apiKeyHelper, kenari claude memberi peringatan dan mengabaikan nilai itu selama sesi. File tersebut tidak diubah.

Untuk memastikan, kirim pesan pertama di dalam tool yang dijalankan lewat wrapper. 401 berarti credential hilang atau dicabut, jadi jalankan kenari login lagi.

Perintah lain

kenari status               # lihat konfigurasi routing, offline
kenari status --check       # periksa juga jaringan, keluar dengan kode bukan nol bila gagal
kenari models               # daftar model beserta harga
kenari reset [claude|codex|grok] # hapus rute, login tetap
kenari logout               # hapus credential kenari dari mesin ini
kenari update --check       # bandingkan versi terpasang dan versi terbaru

kenari reset tidak mengubah konfigurasi native tool maupun login-mu. kenari logout hanya menghapus credential kenari, sehingga role native tetap bisa dipakai.

kenari configure mengunduh katalog model dan menyimpannya selama 24 jam. Konfigurasi yang hanya berisi role native berjalan tanpa login atau katalog. Role yang memakai model kenari gagal dijalankan bila tidak ada katalog atau credential yang valid, atau bila modelnya sudah tidak ada.

File

CLI menyimpan file miliknya di ~/.kenari: config.json, credentials.json, model-cache.json, dan state.json. Di macOS dan Linux, direktorinya hanya bisa diakses olehmu (mode 0700), begitu juga file-nya (mode 0600). Key hanya ada di credentials.json, tidak pernah di konfigurasi Claude Code, Codex, atau Grok, argumen perintah, maupun log.

KENARI_HOME memindahkan direktori ini. KENARI_BASE_URL mengganti gateway kenari, dan HTTP biasa ditolak kecuali KENARI_ALLOW_HTTP=1 diatur untuk pengembangan lokal. CLAUDE_CONFIG_DIR, CODEX_HOME, dan GROK_HOME mengarahkan CLI ke direktori konfigurasi tool tersebut yang bukan default.

Troubleshooting

Gejala	Penyebab	Solusi
`command not found: kenari`	CLI belum terpasang, atau `PATH` tidak mencakup prefix global npm.	Pasang ulang dengan `npm install -g @kenarihq/cli`. Jalankan `npm config get prefix` lalu tambahkan `<prefix>/bin` ke `PATH`.
`credential missing` di `kenari status`	Tidak ada key yang tersimpan.	Jalankan `kenari login`, atau `kenari login --api-key` di server.
`kenari login` tidak selesai	Tidak ada browser di mesin ini, atau login kedaluwarsa setelah 5 menit.	Pakai `kenari login --api-key` dengan key dari halaman API Keys.
`--paste was removed`, atau pesan yang sama untuk `--stdin` atau `--no-browser`	Kamu memakai flag dari CLI versi lama.	Pakai `kenari login --api-key`.
`--api-key takes no value`	Kamu mengirim key sebagai argumen.	Jalankan `kenari login --api-key` dan tempel di prompt, atau alirkan key lewat stdin.
`Kenari login required`	Sebuah role memakai model kenari dan tidak ada key tersimpan.	Jalankan `kenari login`.
`model "kenari/<id>" is not in the Kenari catalog`	Id salah ketik atau modelnya sudah dihapus.	Jalankan `kenari models`, lalu `kenari configure` dengan id yang tercantum.
`check kenari failed: ...` di `kenari status --check`	CLI tidak bisa menjangkau kenari, atau key ditolak.	Periksa jaringan, proxy, dan firewall, lalu login lagi bila key dicabut.
`401` di sesi wrapper	Key dicabut di dashboard.	Jalankan `kenari logout`, lalu `kenari login`.
`402` di sesi wrapper	Model yang dikonfigurasi berbayar dan saldomu Rp 0.	Ganti role ke `kenari/step-3-7-flash:free`, atau top up. Lihat Cara penagihan.