NxCode CLI

Instalasi

Gunakan Node.js 18 atau lebih baru, kemudian pasang NxCode secara global:

npm install --global nxcode-cli
nxcode --version
nxcode --help

Tanpa instalasi global:

npx nxcode-cli --help

Update dan uninstall

npm install --global nxcode-cli@latest
npm uninstall --global nxcode-cli

Uninstall paket tidak menghapus konfigurasi pengguna atau folder .nxcode/ di dalam proyek.

Setup dan konfigurasi

Jalankan wizard dari root proyek. Wizard meminta provider, API key, base URL, dan model, lalu menguji koneksi selama maksimal 15 detik.

nxcode setup
nxcode config
nxcode config --json

Konfigurasi disimpan di %APPDATA%\nxcode\config.json pada Windows atau $XDG_CONFIG_HOME/nxcode/config.json pada Linux/macOS, dengan fallback ke ~/.config/nxcode/config.json. API key selalu dimask saat ditampilkan oleh nxcode config.

Environment override

Provider AI

Wizard menyediakan Anthropic Claude, OpenAI, OpenRouter, DeepSeek, Groq, Ollama, LM Studio, NVIDIA/Nemotron, dan endpoint kustom. Anthropic memakai API Messages; provider lainnya memakai API yang kompatibel dengan OpenAI. Untuk Ollama atau LM Studio, pastikan server lokal telah berjalan.

Fungsi NxCode

NxCode bukan sekadar chat AI di terminal. NxCode memberi AI konteks proyek yang konsisten agar pekerjaan mengikuti rencana, tidak mengulang tugas yang selesai, dan tetap mematuhi pola kode proyek.

Empat lapisan konteks proyek

Data kerja disimpan di folder .nxcode/ pada proyek:

NxCode juga menyimpan backup di .nxcode/backups/ serta riwayat sesi start dan chat sebagai Markdown. Nama file mengikuti nama folder proyek saat ini.

Perintah utama

Gunakan nxcode <perintah> --help untuk melihat seluruh opsi perintah. Untuk otomasi, exit code 0 berarti sukses, 1 error umum, 2 konfigurasi belum lengkap, 3 persetujuan diperlukan atau dibatalkan, dan 4 error provider AI.

Alur kerja dasar

1. Buka terminal pada root proyek.
2. Jalankan nxcode setup untuk menyiapkan konfigurasi.
3. Gunakan nxcode plan untuk menyusun rencana.
4. Jalankan nxcode start untuk mulai mengerjakan proyek.
5. Periksa hasil melalui nxcode progress dan nxcode view status.

cd D:\path\ke\proyek
nxcode setup
nxcode plan
nxcode start

Menyusun plan

nxcode plan memindai proyek dan Git, lalu membuka diskusi perencanaan tanpa langsung menulis file. Tambahkan referensi @file atau @folder, kemudian gunakan /susun atau /draft untuk meminta rancangan. Plan baru disimpan setelah pengguna menyetujui penulisan.

Start dan chat

Project-aware dengan start

nxcode start memakai plan, status, skills, struktur dan kode proyek, status Git, assets, serta aktivitas terminal sebagai konteks. Jika plan belum ada, NxCode dapat menawarkan analisis awal. Edit yang disetujui dicatat ke log aktivitas dan status tugas dapat diperbarui.

Percakapan bebas dengan chat

nxcode chat tidak memuat plan dan status saat startup. Mode ini cocok untuk pertanyaan bebas, tetapi tetap mendukung skills, @mentions, edit file, dan perintah terminal.

nxcode start "implementasikan tugas 2"
nxcode start "tampilkan rencana perubahan" --no-write
nxcode start "ringkas progres" --json
nxcode chat "jelaskan @src/app.js"
nxcode chat "perbaiki @src/app.js" --yes --json
nxcode chat --file src/app.js

Referensi file dengan @mention

Jalankan nxcode assets atau /assets untuk melihat pemetaan kode. Mention folder menyertakan tree dan file teks yang memenuhi batas konteks. Path harus berada di dalam proyek; file rahasia, .env*, private key, sertifikat, node_modules, dan hidden path tidak disertakan. Saat mention dipakai, edit AI dibatasi pada target yang disebut.

Skills proyek

Skills adalah instruksi persisten untuk menjaga pola arsitektur dan gaya kode. Skills dapat merujuk file, direktori, atau aturan inline.

/skill list
/skill add file path/to/README.md
/skill add dir src/components
/skill add style Naming | Gunakan PascalCase untuk komponen
/skill on K1
/skill off K1
/skill rm K1

Slash commands

Perintah berikut tersedia di sesi interaktif utama:

Sesi start juga menyediakan /view, /log, /review, dan /plan. Pada chat, gunakan /file PATH untuk meminta penjelasan file. Ketersediaan integrasi agen bergantung pada instalasi lokal.

Persetujuan dan keamanan

Sebelum perubahan interaktif diterapkan, NxCode menampilkan diff dan menawarkan Allow once, Always allow, atau Deny. Always allow dan /trust hanya berlaku selama sesi berjalan. Backup file aktif secara default.

• --no-write mencegah penulisan file dan eksekusi perintah.
• Perubahan full-file yang tampak memangkas isi secara mencurigakan ditolak saat auto-approved.
• Sejumlah perintah destruktif seperti format drive, shutdown, dan root rm -rf diblokir.
• Perintah normal memiliki timeout lima menit.
• Development server yang dikenali dapat berjalan di background dan dihentikan dengan /stop.

Opsi terminal

• --json — keluaran terstruktur untuk integrasi.
• --quiet — hanya menampilkan error.
• --verbose — menampilkan log debug internal.
• --no-color — menonaktifkan warna terminal.
• --help — menampilkan bantuan perintah.
• --version — menampilkan versi NxCode.

JSON tersedia pada config, view status, progress, review, assets, serta mode one-shot start dan chat. Jika --quiet dan --verbose diberikan bersamaan, quiet diprioritaskan.

Shell completion

nxcode completion bash
nxcode completion fish
nxcode completion ps1

Source hasil Bash dari file profil shell, simpan hasil Fish pada direktori completions Fish, atau dot-source hasil PowerShell dari $PROFILE. Completion juga dapat mengambil kode @asset dari proyek aktif.

Troubleshooting

Not configured atau exit code 2

Jalankan nxcode setup, lalu periksa API key, base URL, dan model melalui nxcode config.

Provider mengembalikan 401 atau 403

Periksa kredensial, endpoint, provider, dan model. NxCode tidak akan memperbaiki kredensial yang ditolak secara otomatis.

Provider mengembalikan 429 atau 5xx

NxCode mencoba ulang dua kali dengan jeda bertahap. Jika tetap gagal, tunggu rate limit pulih atau periksa status provider.

Ollama atau LM Studio tidak terhubung

Pastikan server lokal berjalan dan base URL sesuai. Wizard tetap meminta nilai API key yang tidak kosong meskipun provider lokal mengabaikannya.

Folder .nxcode belum ada

Pastikan terminal berada di root proyek, lalu jalankan nxcode plan atau nxcode start.

@mention tidak ditemukan

Pastikan path berada di bawah root proyek, bukan file rahasia atau path yang dikecualikan. Untuk konteks terlalu besar, ubah limit melalui /setting atau aktifkan unlimited context dengan hati-hati.

approval_required pada mode one-shot

Jalankan ulang dengan --yes untuk menyetujui operasi, atau gunakan --no-write jika hanya ingin melihat preview.

SEARCH/REPLACE atau patch gagal

Isi yang dibuat AI tidak cocok dengan file terbaru. Minta edit yang lebih kecil, baca ulang file, atau minta AI menghasilkan full-file dengan tetap memeriksa diff.