CLI kenari

@kenarihq/cli adalah wrapper resmi kenari untuk memakai model native dan model kenari dalam satu sesi Claude Code atau Codex. Perintah claude dan codex biasa tetap memakai provider native. Rute kenari hanya aktif saat tool dijalankan melalui wrapper.

Ringkasan setup

Ikuti lima langkah ini secara berurutan.

1. Cek prasyarat

node --version

Keluarannya harus v18.0.0 atau lebih baru (LTS apa pun yang lebih baru juga lulus). Jika belum ada, pasang Node.js dari nodejs.org atau lewat package manager (brew install node, nvm install --lts, dan seterusnya).

2. Pasang CLI

npm install -g @kenarihq/cli

3. Login dengan kenari login

kenari login

Perintah ini membuka halaman persetujuan kenari.id di browser. Setelah kamu menekan Approve access, CLI menerima API key baru melalui callback lokal di 127.0.0.1 dan menyimpannya di ~/.kenari/credentials.json (mode 0600 di macOS dan Linux). Key lengkap tidak pernah masuk ke URL browser dan tidak pernah dicetak ke terminal.

Key hasil login berlabel CLI <hostname> dan muncul di halaman API keys pada dashboard. Kamu bisa mencabutnya kapan saja seperti key lain. Penggunaan melalui key ini mengikuti aturan penagihan yang sama dengan key lain di akunmu.

Opsi untuk situasi khusus:

kenari login --no-browser   # tampilkan URL tanpa membuka browser
kenari login --paste        # tempel kode sekali pakai, cocok untuk SSH
printf '%s\n' 'kn-...' | kenari login --stdin   # simpan key yang sudah ada

Pada mode --paste, halaman persetujuan menampilkan kode sekali pakai yang kamu tempel ke terminal. Kode kedaluwarsa dalam 5 menit dan tidak berguna tanpa sesi CLI yang memintanya.

Cek koneksi setelah login:

kenari status --check

Bagian credential menampilkan set jika ~/.kenari/credentials.json ada dan bisa dibaca. Bagian connectivity menampilkan ok jika CLI bisa memanggil /v1/models dengan key itu.

4. Atur rute dengan kenari configure

kenari configure

kenari configure akan meminta tool dan role yang ingin diarahkan ke kenari. Jika Claude Code dan Codex sama-sama terpasang, pilihan default-nya adalah keduanya. Jika hanya satu yang terpasang, tool tersebut dipilih otomatis.

Setiap role bisa tetap memakai native atau diarahkan ke model tetap dengan nilai kenari/<model-id>. Claude Code memiliki role main, opus, sonnet, haiku, fable, dan subagents. Codex memiliki role main, review, dan subagents. main pada Codex juga mendukung picker, sedangkan review dan subagents mendukung inherit.

Contoh konfigurasi non-interaktif:

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

Nilai model tanpa awalan kenari/ selalu menuju provider native. Nilai dengan awalan kenari/ selalu menuju kenari. Wrapper tidak melakukan fallback antar-provider.

Cek konfigurasi:

kenari status

Bagian claude atau codex di keluaran menunjukkan rute per-role yang sedang aktif.

5. Jalankan wrapper

kenari claude [argumen...]
kenari codex [argumen...]

Setiap pemanggilan menyalakan router privat pada port acak di 127.0.0.1, menjalankan CLI asli dengan override yang hanya berlaku untuk proses tersebut, meneruskan input terminal dan signal, lalu mematikan router saat proses selesai. Wrapper tidak menulis provider atau credential ke konfigurasi Claude Code maupun Codex.

Cek koneksi dari dalam wrapper: kirim pesan pertama ke kenari claude. Jika CLI menampilkan 401 invalid x-api-key, jalankan kenari status --check untuk melihat apakah credential masih set. Jika menampilkan model_not_found, id model salah ketik. Cek id di Model & harga.

Perintah lain

kenari status              # lihat konfigurasi rute secara offline
kenari status --check      # periksa rute dan koneksi
kenari models              # daftar model beserta harga
kenari reset [claude|codex] # hapus pilihan rute, tanpa menghapus login
kenari logout              # hapus credential kenari dari mesin ini

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

Troubleshooting

Gejala	Penyebab	Solusi
command not found: kenari	CLI belum terpasang atau PATH tidak mencakup prefix global npm	pasang ulang lewat npm install -g @kenarihq/cli. Cek npm config get prefix dan tambahkan <prefix>/bin ke PATH
kenari status --check menampilkan credential: missing	~/.kenari/credentials.json tidak ada	jalankan kenari login lagi
kenari status --check menampilkan connectivity: failed dengan 401	key dicabut di dashboard atau tersimpan sebagian	jalankan kenari logout lalu kenari login
kenari status --check menampilkan connectivity: failed dengan 402	model yang dikonfigurasi berbayar dan saldo Rp 0	ganti role ke kenari/step-3-7-flash:free, atau isi saldo
Wrapper hang setelah startup	router lokal bentrok dengan proses lain	tutup proses Claude Code atau Codex lain yang berjalan. Router memakai port acak, jadi tabrakan hanya terjadi pada sesi paralel