Halaman ini diterjemahkan dari dokumentasi bahasa Inggris. Perintah, pengenal, dan contoh tidak diubah. Runtime 7.24.4 · SDK 2.6.7. Sumber bahasa Inggris

CLI tanpa interaksi (ax-code run)

Status: Aktif Cakupan: kondisi terkini Terakhir ditinjau: 2026-09-22 Pemilik: pengelola runtime AX Code

ax-code run adalah titik masuk sekali jalan dan noninteraktif untuk agen pengodean AI serta skrip. Ia mengirim satu prompt, mencetak balasan akhir asisten, lalu keluar — tanpa antarmuka terminal, tanpa prompt interaktif. Panduan ini mencakup permukaan opsi, kontrak keluaran, kode keluar, dan resep salin-tempel untuk skrip serta CI.

Memanggil sebuah jalankan

Ada empat cara memasok prompt. Mereka tersusun berurutan: --prompt-file, lalu -p/--prompt, lalu pesan posisional, lalu stdin yang dialirkan.

# Positional after -- (safest; flags after -- are never consumed as options)
ax-code run --model qwen -- "Review this change"

# Explicit prompt flag
ax-code run --model qwen --prompt "Review this change"
ax-code run --model qwen -p "Review this change"

# Prompt read from a file (not an attachment)
ax-code run --model qwen --prompt-file ./prompt.txt

# Piped stdin (used as the prompt when no positional/--prompt is given)
printf 'Review this change' | ax-code run --model qwen

Bila stdin bukan TTY, isinya ditambahkan ke prompt yang tersusun, jadi ia menjadi seluruh prompt bila tidak ada yang lain dipasok. Pembaca stdin menunggu jendela tenang 300 ms sebelum menyerah pada pipa yang masih terbuka, jadi tulis prompt segera dan tutup stdin — atau pakai --prompt-file untuk prompt yang besar atau dihasilkan perlahan. --prompt-file - membaca prompt dari stdin secara eksplisit (kesalahan pemakaian bila stdin adalah TTY); penambahan stdin tersirat tidak pernah berjalan untuk kedua kalinya pada pemanggilan itu.

-f/--file melampirkan berkas ke pesan dan tidak pernah mengganti prompt; opsi ini dapat diulang:

ax-code run --model qwen --file README.md --file src/main.ts -- "Summarize these"

Lampiran harus berada di dalam direktori proyek: server menolak lampiran di luarnya terlepas dari aturan izin, jadi CLI menolaknya di muka dengan kesalahan pemakaian. Salin berkas ke dalam proyek atau teruskan isinya dengan --prompt-file. --add-dir memberi alat akses ke direktori tambahan tetapi tidak mengubah aturan ini.

Jenis mime lampiran disimpulkan dari ekstensi: png, jpg, jpeg, gif, dan webp dipetakan ke jenis image/* mereka dan pdf ke application/pdf, jadi lampiran biner sampai ke server sebagai jenis aslinya, bukan text/plain. Yang lain — termasuk berkas tanpa ekstensi yang dikenali — dikirim sebagai text/plain, dan lampiran direktori diklasifikasikan application/x-directory.

Mengarahkan jalankan

Tiga bendera mengarahkan jalankan tanpa mengubah teks prompt. Semuanya hanya bentuk panjang dan kebab-case.

--append-system-prompt TEXT / --append-system-prompt-file PATH

Menambahkan teks ekstra ke prompt sistem setelah prompt sistem agen dan lingkungan — ia menambahkan dan tidak pernah mengganti prompt sistem bawaan. Kedua bentuk saling eksklusif. Varian berkas nyaman untuk instruksi yang lebih panjang; tepat satu baris baru di akhir dipangkas, dan teks kosong (atau berkas yang tidak dapat dibaca) adalah kesalahan pemakaian sebelum apa pun dikirim.

ax-code run --model qwen --append-system-prompt "Answer in English only" -- "Review this change"

--disallowed-tools a,b

Menonaktifkan alat berdasarkan id untuk jalankan ini (dipisah koma, dapat diulang). Ia diterapkan melalui kedua mekanisme server: aturan tolak pada sesi yang dibuat mencakup jalankan baru, dan peta alat per permintaan juga mencakup jalankan --session/--continue yang dilanjutkan. Menolak bash juga menolak perintah alat monitor, yang berjalan melalui peluncur shell yang sama; panggilan yang mengenai aturan tolak gagal sebagai kesalahan alat dan dihitung sebagai penolakan untuk status jalankan yang diblokir. Id yang tidak dikenal bukan kesalahan — id alat MCP bersifat dinamis — tetapi pada format bawaan setiap id di luar himpunan alat bawaan mencetak satu peringatan stderr (ditekan oleh --quiet).

ax-code run --model qwen --disallowed-tools bash,write -- "Audit this module without mutating anything"

--add-dir PATH

Memberi agen akses ke satu direktori tambahan (dapat diulang): aturan izinkan external_directory untuk <resolved-path>/* ditambahkan ke aturan izin sesi baru, mencakup direktori itu dan segala sesuatu di bawahnya. Setiap jalur harus ada dan berupa direktori (diselesaikan terhadap cwd pemanggil seperti --file). Aturan diterapkan saat sesi dibuat, jadi di bawah --session/--continue ia tidak dapat berlaku — CLI mencetak --add-dir applies only to new sessions di stderr dan melanjutkan. Ia tidak mengubah pembatasan --file: lampiran tetap harus berada di dalam direktori proyek. Ia mencakup alat berkas (baca, glob, grep, daftar, sunting, tulis); perintah shell yang menjangkau direktori melalui jalur dinamis tetap memicu prompt akses jalur yang hanya interaktif, yang ditolak otomatis oleh jalankan headless, jadi utamakan alat berkas atau teruskan isi berkas secara eksplisit.

ax-code run --model qwen --add-dir ../design-docs -- "Read ../design-docs/spec.md and summarize it"

Memilih model

Cantumkan ID yang dapat dipakai dengan ax-code models. Teruskan nilai provider/model yang dihasilkan ke --model (-m):

ax-code models            # one "provider/model" ID per line
ax-code models --json     # one JSON document

ax-code models --json mencetak satu dokumen berbentuk {"models":[{"id":"provider/model","provider":"...","model":"...","connected":true}]}.

Nama keluarga deepseek, glm, dan qwen diselesaikan ke bawaan Flash mereka, jadi ax-code run --model qwen -- "..." berfungsi tanpa menuliskan ID provider/model yang lengkap. Menghilangkan --model memakai bawaan yang dikonfigurasi; agen dan model efektif dicetak ke stderr sebagai > Agent · model.

Format keluaran

--format menerima default (bawaan), json, jsonl, atau ndjson (jsonl dan ndjson adalah alias untuk json).

Bawaan (teks)

Format bawaan hanya mencetak teks akhir asisten di stdout. Semua kemajuan, aktivitas alat, dan diagnostik pergi ke stderr, diawali header > Agent · model · ses_... yang mencakup id sesi, jadi pemanggil multi-giliran dapat melanjutkan dengan --session tanpa beralih ke --format json (--quiet menekan header). Warna ANSI dinonaktifkan bila stderr bukan TTY atau bila NO_COLOR disetel (nilai apa pun), jadi jalankan yang dialirkan tidak pernah memancarkan kode pelarian.

Aliran JSON (--format json)

--format json mencetak aliran peristiwa JSON yang dipisah baris baru (NDJSON) — satu objek JSON per baris, bukan satu dokumen JSON tunggal. Peristiwa mencakup step_start, text, tool_use, reasoning (hanya dengan --thinking), permission_denied, error, dan step_finish. Aliran selalu berakhir dengan tepat satu baris result:

{
  "type": "result",
  "timestamp": 1727000000000,
  "sessionID": "ses_...",
  "status": "completed",
  "text": "...",
  "permissionDenials": 0,
  "usage": { "input": 1200, "output": 80, "reasoning": 0, "cacheRead": 0, "cacheWrite": 0 }
}

status adalah completed, blocked, atau error. usage hanya membawa jumlah token — input, output, reasoning, cacheRead, cacheWrite — dan dihilangkan seluruhnya bila jumlahnya tidak diketahui; tidak ada bidang biaya. Bila sebuah jalankan gagal sebelum pengiriman (bendera buruk, model tidak dikenal, dan sebagainya), format aliran mencetak satu baris sebelum keluar:

{ "type": "error", "error": { "code": "usage", "message": "..." } }

error.code adalah salah satu dari:

Kode keluar

Sandbox

--sandbox read-only|workspace-write|full-access memilih mode isolasi (bawaan full-access). Pada jalankan headless permintaan izin ditolak otomatis dan dilaporkan sebagai peristiwa permission_denied, jadi jalankan yang membutuhkan penulisan yang tidak diizinkan melaporkan blocked dan keluar 3. Ini mencakup subagen juga: permintaan yang muncul di sesi anak yang dibuat oleh alat task ditolak dengan cara yang sama, dan peristiwa permission_denied mereka membawa sessionID anak. Panggilan alat yang ditolak oleh aturan tolak izin (misalnya dari --disallowed-tools) atau oleh sandbox hanya-baca juga dihitung sebagai penolakan. Alat interaktif question dan plan_exit selalu dinonaktifkan pada jalankan headless, termasuk pada sesi yang dilanjutkan. Pakai read-only hanya bila tidak ada mutasi yang diharapkan; workspace-write menjaga penulisan di dalam proyek.

Di bawah --attach bendera juga dikirim sebagai kebijakan isolasi per permintaan di setiap isi prompt; server menerapkan yang lebih ketat antara modenya sendiri dan kebijakan yang diminta, jadi ia hanya dapat memperketat. Kebijakan per permintaan yang sama dikirim untuk server yang dimiliki secara lokal, sehingga perilaku tetap seragam.

Keluaran terstruktur

-o/--output-file <path> menulis teks akhir asisten ke sebuah berkas. --output-schema <file> memvalidasi teks akhir sebagai JSON terhadap berkas JSON Schema; ketidakcocokan dilaporkan sebagai peristiwa error dengan result.status error dan keluar dengan kode 1. Berkas skema diperiksa sebelum model berjalan — skema yang tidak dapat dibaca, tidak dapat diurai, atau bukan objek adalah kesalahan pemakaian sebelum apa pun dikirim. Saat berhasil, skema yang diurai juga dikirim ke model sebagai format keluaran json_schema jalankan, dan server mencoba ulang balasan yang tidak valid hingga dua kali sebelum validasi akhir milik CLI berjalan sebagai pengaman. Keluaran akhir adalah objek terstruktur yang diserialkan (satu baris JSON): itulah yang dibawa stdout, --output-file, dan result.text:

ax-code run --model qwen --output-schema ./answer.schema.json -- "Return a JSON object with a summary field"

Sesi dan pelanjutan

• -c/--continue — lanjutkan sesi terbaru.
• -s/--session <id> — lanjutkan sesi tertentu berdasarkan ID.
• --fork — cabangkan sesi sebelum melanjutkan (membutuhkan --continue atau --session).
• --show-history — cetak riwayat sesi yang terlihat saat melanjutkan (membutuhkan --continue atau --session).
• --attach <url> — lampirkan ke server yang sudah berjalan alih-alih memulai satu; gabungkan dengan --dir untuk menargetkan direktori proyek di server itu. Server yang dilindungi dengan AX_CODE_SERVER_PASSWORD menerima --password (atau variabel yang sama di sisi pemanggil); runtime terkelola mengambil tokennya dari AX_CODE_RUNTIME_TOKEN.
• --runtime — lampirkan ke runtime terkelola direktori proyek (--dir atau cwd pemanggil) yang dimulai dengan ax-code runtime start, menyelesaikan URL dan tokennya dari catatan runtime privat. Bila tidak ada runtime yang berjalan, jalankan gagal sebelum permintaan apa pun dengan kode kesalahan attach dan pesan yang menamai perintah mulai. --runtime dan --attach saling eksklusif.

Resep

Sekali jalan

ax-code run --model qwen -- "Fix the failing test in src/parser.ts"

Batasi jalankan dengan batas waktu

ax-code run --timeout 120 --model qwen -- "Fix the failing test in src/parser.ts"

--timeout <seconds> menggugurkan jalankan di server dan keluar 124 (result.status adalah timeout) bila jalankan melampaui batas, jadi agen yang macet tidak dapat menahan pekerjaan CI terbuka tanpa batas. Batas mencakup seluruh pemanggilan — ia dipersenjatai sebelum panggilan server pertama, jadi bahkan host --attach yang lubang hitam atau mulai yang menggantung berakhir tepat waktu (pada kasus awal itu baris hasil membawa sessionID kosong).

Tunggu subagen latar belakang

ax-code run --await-background 300 --timeout 360 --model qwen -- \
  "Delegate the independent checks, then integrate their results"

--await-background <seconds> menjaga pemanggilan ini tetap terbuka untuk anak task latar belakang yang dibuat oleh sesinya dan giliran tindak lanjut induk yang dipicu oleh hasil mereka. Opsi ini bersifat ikut serta dan dibatasi 3600 detik. Balasan akhir dan result.text JSON berasal dari giliran induk terakhir yang selesai. Jika anak atau tindak lanjut mereka tidak selesai dalam batas tunggu, jalankan melaporkan kesalahan dan keluar 1. --timeout tetap menjadi batas keseluruhan. Tugas terjadwal proyek berjalan di sesi terpisah dan bukan bagian dari tunggu ini. Perintah sekali jalan ini tidak mengklaim jadwal proyek yang jatuh tempo; backend yang persisten memiliki pengirimannya.

Urai aliran JSON

result=$(ax-code run --format json --model qwen -- "..." | tail -n 1)
echo "$result" | jq -r '.status'
echo "$result" | jq -r '.text'

Baris result selalu merupakan baris terakhir, jadi tail -n 1 mengisolasinya bahkan bila aliran berakhir lebih awal.

Tinjauan hanya-baca

ax-code run --sandbox read-only --model qwen -- "Review this diff for bugs"

Keluaran JSON terstruktur dengan skema

cat > answer.schema.json <<'JSON'
{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}
JSON
ax-code run --model qwen --output-schema answer.schema.json --output-file answer.json \
  -- "Return JSON with a one-sentence summary"

Lanjutkan sesi

# Start a session and note the sessionID from the result line
ax-code run --format json --model qwen -- "Draft the outline" | tail -n 1

# Continue it
ax-code run --model qwen --session ses_... -- "Now write section 2"

Lampirkan berkas

ax-code run --model qwen --file docs/spec.md -- "Summarize the attached spec"

Perintah yang dapat dibaca mesin

ax-code run --format json memancarkan aliran peristiwa yang dipisah baris baru (lihat aliran JSON); itu satu-satunya permukaan --json yang mengalirkan. Setiap perintah hanya-baca lain yang membawa bendera --json mengikuti kontrak yang lebih ketat: saat berhasil ia menulis tepat satu dokumen JSON ke stdout, dan saat gagal stdout tetap kosong sementara satu dokumen {"error":{"code","message"}} pergi ke stderr dan kode keluarnya 1.

Perintah dengan --json:

• ax-code session list --json
• ax-code models --json
• ax-code providers list --json
• ax-code agent list --json
• ax-code mcp list --json
• ax-code mcp auth list --json
• ax-code stats --json
• ax-code context --json
• ax-code memory status --json
• ax-code memory list --json
• ax-code task list --json / ax-code task show <taskID> --json
• ax-code schedule list --json / ax-code schedule show <taskID> --json
• ax-code runtime list --json / ax-code runtime status --json
• ax-code doctor --json
• ax-code risk <sessionID> --json
• ax-code wiki status --json
• ax-code workflow list --json / ax-code workflow status <runID> --json

ax-code runtime status mencetak dokumen JSON-nya tanpa syarat — bendera --json diterima demi konsistensi tetapi tindakan status selalu memancarkan JSON di stdout.

Memanggil ax-code dari agen lain

Saat membungkus ax-code run dari skrip, langkah CI, atau agen lain:

• Pakai --format json dan baca baris terakhir — catatan result selalu merupakan baris akhir, bahkan bila aliran berakhir lebih awal.
• Ambil sessionID dari baris hasil itu untuk giliran tindak lanjut apa pun; kembalikan dengan --session.
• Jangan pernah memakai --continue dari pemanggil yang bersamaan — ia melanjutkan sesi terbaru, yang berlomba bila beberapa pemanggil aktif; teruskan id --session yang eksplisit sebagai gantinya.
• Teruskan --model yang eksplisit agar jalankan tidak bergantung pada bawaan terkonfigurasi yang dapat berubah.
• Selalu teruskan --timeout agar agen yang macet tidak dapat menahan pemanggil tetap terbuka.
• Tutup stdin, atau pakai --prompt-file / --prompt-file -: pembaca pipa tersirat menyerah setelah jendela tenang 300 ms dan memotong pipa yang lambat secara diam-diam.
• Setel NO_COLOR=1, atau andalkan deteksi non-TTY, agar jalankan yang dialirkan tidak pernah memancarkan kode pelarian ANSI.
• Jalankan dari direktori proyek: direktori rumah atau induk multi-repositori ditolak dalam mode noninteraktif. Setel AX_CODE_ALLOW_BROAD_DIR=1 untuk menimpa penjagaan itu.
• Kegagalan pemakaian tidak mencetak apa pun di stdout (bantuan dan kesalahan satu baris pergi ke stderr), jadi perintah yang salah ketik meninggalkan stdout kosong dengan keluar 1. Di bawah --format json kegagalan pemakaian juga ditulis sebagai satu baris error di stdout.
• Sinyal yang tiba saat proses masih memuat, sebelum perintah run aktif, mengakhiri proses dengan keluar 130 dan tanpa keluaran; setelah perintah aktif, SIGINT dan SIGTERM selalu menghasilkan satu baris terminal result dengan status cancelled.