Bu sayfa İngilizce belgenin çevirisidir. Komutlar, tanımlayıcılar ve örnekler aynıdır. Çalışma zamanı 7.24.4 · SDK 2.6.7. İngilizce kaynak

Başsız CLI (ax-code run)

Durum: Etkin Kapsam: güncel durum Son inceleme: 2026-09-22 Sahip: AX Code çalışma zamanı bakımcıları

ax-code run, yapay zeka kodlama ajanları ve betikler için tek seferlik, etkileşimsiz giriş noktasıdır. Tek bir istem gönderir, asistanın son yanıtını yazdırır ve çıkar; terminal arayüzü yoktur, etkileşimli soru yoktur. Bu rehber seçenek yüzeyini, çıktı sözleşmesini, çıkış kodlarını ve betikleme ile CI için kopyala-yapıştır tariflerini kapsar.

Çalıştırmayı başlatma

İstemi vermenin dört yolu vardır. Sırayla birleşirler: --prompt-file, ardından -p/--prompt, ardından konumsal ileti, ardından borulanmış stdin.

# 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

stdin bir TTY değilse içeriği birleşik isteme eklenir; başka bir şey verilmemişse istemin tamamı odur. stdin okuyucusu açık bir borudan vazgeçmeden önce 300 ms sessiz pencere bekler; istemi hemen yazın ve stdin kapatın ya da büyük veya yavaş üretilen istemler için --prompt-file kullanın. --prompt-file - istemi stdin üzerinden açıkça okur (stdin bir TTY ise kullanım hatası); örtük borulu stdin eklemesi aynı çağrıda ikinci kez çalışmaz.

-f/--file dosyaları iletiye ekler ve istemin yerini asla almaz; tekrarlanabilir:

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

Bir ek proje dizininin içinde durmalıdır: sunucu, izin kurallarından bağımsız olarak dışarıdaki ekleri reddeder; bu yüzden CLI onları baştan bir kullanım hatasıyla geri çevirir. Dosyayı projeye kopyalayın veya içeriğini --prompt-file ile geçirin. --add-dir araçlara ek dizinlere erişim verir ancak bu kuralı değiştirmez.

Ek MIME türleri uzantıdan çıkarılır: png, jpg, jpeg, gif ve webp kendi image/* türüne, pdf ise application/pdf türüne eşlenir; ikili ekler sunucuya text/plain yerine gerçek türleriyle ulaşır. Başka her şey, tanınmayan uzantılı bir dosya dahil, text/plain olarak gönderilir ve bir dizin eki application/x-directory olarak sınıflanır.

Çalıştırmayı yönlendirme

Üç bayrak, istem metnini değiştirmeden bir çalıştırmayı yönlendirir. Hepsi yalnızca uzun biçimdedir ve kebab-case kullanır.

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

Ajan ve ortam sistem istemlerinden sonra sistem istemine ek metin ekler; ekler ve yerleşik sistem isteminin yerini asla almaz. İki biçim birbirini dışlar. Dosya biçimi daha uzun yönergeler için uygundur; tam olarak bir sondaki satır sonu kırpılır ve boş bir metin (veya okunamayan dosya), herhangi bir şey gönderilmeden önce kullanım hatasıdır.

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

--disallowed-tools a,b

Çalıştırma için araçları kimliğe göre kapatır (virgülle ayrılmış, tekrarlanabilir). Her iki sunucu mekanizmasıyla uygulanır: oluşturulan oturumdaki ret kuralları yeni çalıştırmaları kapsar ve istek başına araç haritası sürdürülen --session/--continue çalıştırmalarını da kapsar. bash reddi, aynı kabuk başlatıcısından geçen monitor aracının komutunu da reddeder; ret kuralına çarpan bir çağrı araç hatası olarak başarısız olur ve engellenmiş çalıştırma durumu için bir ret sayılır. Bilinmeyen kimlikler hata değildir; MCP araç kimlikleri dinamiktir. Varsayılan biçimde yerleşik araç kümesinin dışındaki her kimlik stderr üzerine bir uyarı yazar (--quiet ile bastırılır).

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

--add-dir PATH

Ajana bir ek dizine erişim verir (tekrarlanabilir): external_directory izin kuralı <resolved-path>/* için yeni oturumun izin kurallarına eklenir ve dizini ile altındaki her şeyi kapsar. Her yol var olmalı ve bir dizin olmalıdır (çağıranın cwd değerine göre --file gibi çözülür). Kural oturum oluşturulurken uygulanır; bu yüzden --session/--continue altında geçerli olamaz. CLI stderr üzerine --add-dir applies only to new sessions yazar ve sürdürür. --file kapsamasını değiştirmez: ekler yine proje dizininin içinde durmalıdır. Dosya araçlarını kapsar (read, glob, grep, list, edit, write); dinamik bir yolla dizine ulaşan bir kabuk komutu yine de yalnızca etkileşimli yol erişim istemini tetikler. Başsız bir çalıştırma bu istemi otomatik reddeder; dosya araçlarını yeğleyin veya dosya içeriğini açıkça geçirin.

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

Model seçme

Kullanılabilir kimlikleri ax-code models ile listeleyin. Ortaya çıkan provider/model değerini --model değerine geçirin (-m):

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

ax-code models --json biçimi {"models":[{"id":"provider/model","provider":"...","model":"...","connected":true}]} olan tek bir belge yazdırır.

Aile adları deepseek, glm ve qwen Flash varsayılanlarına çözülür; bu yüzden ax-code run --model qwen -- "..." tam bir provider/model kimliği yazılmadan çalışır. --model atlanırsa yapılandırılmış varsayılan kullanılır; etkin ajan ve model stderr üzerine > Agent · model olarak yazılır.

Çıktı biçimleri

--format şunları kabul eder: default (varsayılan), json, jsonl veya ndjson (jsonl ve ndjson, json için takma adlardır).

Varsayılan (metin)

Varsayılan biçim stdout üzerine yalnızca son asistan metnini yazar. Tüm ilerleme, araç etkinliği ve tanı bilgisi stderr üzerine gider ve oturum kimliğini içeren bir > Agent · model · ses_... başlığıyla başlar; çok turlu bir çağıran --session ile sürdürebilir ve --format json biçimine geçmez (--quiet başlığı bastırır). ANSI renkleri stderr bir TTY değilken veya NO_COLOR ayarlıyken (herhangi bir değer) kapanır; borulanmış bir çalıştırma kaçış kodu üretmez.

JSON akışı (--format json)

--format json satır sonuyla ayrılmış bir JSON (NDJSON) olay akışı yazar: satır başına bir JSON nesnesi, tek bir JSON belgesi değil. Olaylar şunları içerir: step_start, text, tool_use, reasoning (yalnızca --thinking ile), permission_denied, error ve step_finish. Akış her zaman tam olarak bir result satırıyla biter:

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

status değeri completed, blocked veya error olur. usage yalnızca belirteç sayılarını taşır: input, output, reasoning, cacheRead, cacheWrite. Sayılar bilinmiyorsa tamamen atlanır; maliyet alanı yoktur. Bir çalıştırma gönderilmeden önce başarısız olursa (hatalı bayrak, bilinmeyen model vb.) akış biçimi çıkmadan önce bir satır yazar:

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

error.code şunlardan biridir:

Çıkış kodları

Sandbox

--sandbox read-only|workspace-write|full-access yalıtım kipini seçer (varsayılan full-access). Başsız çalıştırmalarda izin soruları otomatik reddedilir ve permission_denied olayları olarak bildirilir; izin verilmeyen bir yazma gereken çalıştırma blocked bildirir ve 3 ile çıkar. Bu alt ajanları da kapsar: task aracının oluşturduğu alt oturumlardaki sorular aynı biçimde reddedilir ve onların permission_denied olayları alt sessionID değerini taşır. Bir izin ret kuralıyla (örneğin --disallowed-tools kaynaklı) veya salt okunur sandbox ile reddedilen araç çağrıları da ret sayılır. Etkileşimli question ve plan_exit araçları, sürdürülen oturumlar dahil, başsız bir çalıştırmada her zaman kapalıdır. read-only yalnızca değişiklik beklenmiyorsa kullanın; workspace-write yazmaları proje içinde tutar.

--attach altında bayrak her istem gövdesinde istek başına yalıtım ilkesi olarak da gönderilir; sunucu kendi kipi ile istenen ilkenin daha sıkı olanını uygular, yani yalnızca sıkılaştırabilir. Aynı istek başına ilke yerel sahipli sunucular için de gönderilir ve davranış tekdüze kalır.

Yapılandırılmış çıktı

-o/--output-file <path> son asistan metnini bir dosyaya yazar. --output-schema <file> son metni bir JSON Schema dosyasına karşı JSON olarak doğrular; uyuşmazlık bir error olayı olarak result.status error ile bildirilir ve çıkış kodu 1 olur. Şema dosyası model çalışmadan önce ön denetlenir: okunamayan, ayrıştırılamayan veya nesne olmayan bir şema, herhangi bir şey gönderilmeden önce kullanım hatasıdır. Başarıda ayrıştırılmış şema modele çalıştırmanın json_schema çıktı biçimi olarak da gönderilir ve sunucu geçersiz bir yanıtı en fazla iki kez yeniden dener; ardından CLI kendi son doğrulamasını son çare olarak çalıştırır. Son çıktı serileştirilmiş yapılandırılmış nesnedir (tek satır JSON): stdout, --output-file ve result.text bunu taşır:

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

Oturumlar ve sürdürme

• -c/--continue — en son oturumu sürdürün.
• -s/--session <id> — belirli bir oturumu kimlikle sürdürün.
• --fork — sürdürmeden önce oturumu çatallayın (--continue veya --session gerekir).
• --show-history — sürdürürken görünür oturum geçmişini yazdırın (--continue veya --session gerekir).
• --attach <url> — bir sunucu başlatmak yerine zaten çalışan bir sunucuya bağlanın; o sunucudaki bir proje dizinini hedeflemek için --dir ile birleştirin. AX_CODE_SERVER_PASSWORD ile korunan bir sunucu --password alır (veya çağıran tarafta aynı değişken); yönetilen bir çalışma zamanı belirtecini AX_CODE_RUNTIME_TOKEN üzerinden alır.
• --runtime — proje dizininin yönetilen çalışma zamanına bağlanın (--dir veya çağıranın cwd değeri); kayıt ax-code runtime start ile başlatılmıştır ve URL ile belirteç özel çalışma zamanı kaydından çözülür. Çalışan bir çalışma zamanı yoksa çalıştırma herhangi bir istekten önce attach hata koduyla ve başlatma komutunu adlandıran bir iletiyle başarısız olur. --runtime ile --attach birbirini dışlar.

Tarifler

Tek seferlik

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

Bir çalıştırmayı zaman aşımıyla sınırlama

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

--timeout <seconds>, çalıştırma sınırı aştığında sunucudaki çalıştırmayı durdurur ve 124 ile çıkar (result.status değeri timeout); takılı bir ajan bir CI işini sonsuza dek açık tutamaz. Sınır tüm çağrıyı kapsar ve ilk sunucu çağrısından önce kurulur; kara deliğe düşmüş bir --attach ana makinesi veya askıda kalan bir başlangıç zamanında sonlanır (o erken durumda sonuç satırı boş bir sessionID taşır).

Arka plan alt ajanlarını bekleme

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

--await-background <seconds> bu çağrıyı, oturumunun oluşturduğu arka plan task çocukları ve sonuçlarının tetiklediği üst takip turları için açık tutar. İsteğe bağlıdır ve 3600 saniye ile sınırlıdır. Son yanıt ve JSON result.text son tamamlanan üst turdan gelir. Çocuklar veya takipleri bekleme sınırı içinde durulmazsa çalıştırma bir hata bildirir ve 1 ile çıkar. --timeout genel sınır olarak kalır. Proje zamanlanmış görevleri ayrı oturumlarda çalışır ve bu beklemeye dahil değildir. Bu tek seferlik komut vadesi gelen proje zamanlamalarını üstlenmez; dağıtımı kalıcı bir arka uç sahiplenir.

JSON akışını ayrıştırma

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

result satırı her zaman son satırdır; bu yüzden tail -n 1 akış erken bitse bile onu ayırır.

Salt okunur inceleme

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

Şema ile yapılandırılmış JSON çıktısı

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"

Bir oturumu sürdürme

# 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"

Bir dosya ekleme

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

Makinece okunur komutlar

ax-code run --format json satır sonuyla ayrılmış bir olay akışı yayar (JSON akışı bölümüne bakın); akan tek --json yüzeyidir. --json bayrağı taşıyan diğer her salt okunur komut daha sıkı bir sözleşme izler: başarıda stdout üzerine tam olarak bir JSON belgesi yazar; başarısızlıkta stdout boş kalır, tek bir {"error":{"code","message"}} belgesi stderr üzerine gider ve çıkış kodu 1 olur.

--json taşıyan komutlar:

• 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 JSON belgesini koşulsuz yazdırır. --json bayrağı tutarlılık için kabul edilir ancak durum eylemi stdout üzerine her zaman JSON yayar.

Başka bir ajandan ax-code çağırma

Bir betikten, bir CI adımından veya başka bir ajandan ax-code run sarmalanırken:

• --format json kullanın ve son satırı okuyun. result kaydı, akış erken bitse bile her zaman son satırdır.
• Herhangi bir takip turu için o sonuç satırından sessionID değerini alın; --session ile geri geçirin.
• Eşzamanlı çağıranlardan --continue kullanmayın; en son oturumu sürdürür ve birden fazla çağıran etkinken yarış oluşur. Bunun yerine açık bir --session kimliği geçirin.
• Çalıştırmanın değişebilir yapılandırılmış varsayılana bağlı kalmaması için açık bir --model geçirin.
• Takılı bir ajanın çağıranı açık tutamaması için her zaman --timeout geçirin.
• stdin kapatın veya --prompt-file / --prompt-file - kullanın: örtük boru okuyucusu 300 ms sessiz pencereden sonra vazgeçer ve yavaş bir boruyu sessizce keser.
• NO_COLOR=1 ayarlayın veya TTY olmayan algılamaya güvenin; borulanmış bir çalıştırma ANSI kaçış kodu üretmesin.
• Proje dizininden çalıştırın: etkileşimsiz kipte bir ev dizini veya çok depolu üst dizin reddedilir. Bu korumayı geçersiz kılmak için AX_CODE_ALLOW_BROAD_DIR=1 ayarlayın.
• Kullanım başarısızlıkları stdout üzerine hiçbir şey yazmaz (yardım ve tek satırlık hata stderr üzerine gider); yanlış yazılmış bir komut stdout boş ve çıkış 1 bırakır. --format json altında kullanım başarısızlığı stdout üzerine tek bir error satırı olarak da yazılır.
• Süreç hâlâ yüklenirken, run komutu etkinleşmeden gelen bir sinyal süreci çıktısız ve 130 çıkış koduyla bitirir; komut etkinleştikten sonra SIGINT ve SIGTERM her zaman tek uç result satırını üretir ve durum cancelled olur.