Claude Code Headless: टर्मिनल से अपने डिप्लॉयमेंट की जाँच करें

Claude Code का headless मोड claude -p के साथ आपके टर्मिनल से एक प्रॉम्प्ट चलाता है और टास्क पूरा होते ही बंद हो जाता है। आप इसमें डेटा पाइप कर सकते हैं, जवाब सेव कर सकते हैं और इसे किसी स्क्रिप्ट से कॉल कर सकते हैं। यह गाइड इसका इस्तेमाल डिप्लॉयमेंट की जाँच समझाने के लिए करती है: एक हेल्थ एंडपॉइंट, एक प्राइस कोट (कीमत का हिसाब) और एक रिपोर्ट जिसे आपकी स्क्रिप्ट जाँच सकती है।

यह उदाहरण एक आम गड़बड़ी पकड़ता है: /healthz HTTP 200 लौटाता है, जबकि ऐप्लिकेशन का असली रूट 503 लौटाता है। आपको एक ऐसा डेमो मिलेगा जिसे दोहराया जा सकता है, एक JSON रिपोर्ट, और ऐप्लिकेशन की जाँच फ़ेल होने पर शून्य के अलावा कोई एग्ज़िट कोड।

एक नॉन-इंटरैक्टिव कमांड से शुरू करें

Claude Code इंस्टॉल करके साइन इन करने के बाद यह चलाएँ:

claude -p "Explain what an HTTP 503 response tells me in two sentences." \
  --tools ""

-p का मतलब है नतीजा प्रिंट करो और बाहर निकलो। --tools "" इस सवाल के लिए बिल्ट-इन टूल्स बंद कर देता है। Claude आपकी रिपॉज़िटरी पढ़े बिना या कोई शेल कमांड चलाए बिना सिर्फ़ प्रॉम्प्ट से जवाब दे सकता है। उपलब्ध फ़्लैग्स की सूची Claude Code CLI रेफ़रेंस में है।

डिप्लॉयमेंट की जाँच के लिए मॉडल को वे ऑब्ज़र्वेशन दें जो आपकी स्क्रिप्ट पहले ही इकट्ठा कर चुकी है। इससे हर HTTP रिक्वेस्ट और पास होने की शर्त को जाँचना आसान हो जाता है। साथ ही डिप्लॉयमेंट क्रेडेंशियल मॉडल के इनपुट से बाहर रहते हैं।

आपको क्या चाहिए

Python 3.10 या उसके बाद का वर्ज़न, Claude Code का मौजूदा इंस्टॉलेशन और एक साइन-इन किया हुआ अकाउंट। डेमो सिर्फ़ Python की standard library इस्तेमाल करता है, इसलिए कोई Python पैकेज इंस्टॉल नहीं करना पड़ता। शेल उदाहरण macOS या Linux पर Bash या Zsh में चलाएँ।

इंस्टॉल किया गया CLI और उसका ऑथेंटिकेशन स्टेटस जाँचें:

claude --version
claude auth status

अगर सेव किया गया सेशन एक्सपायर होने से कोई रिक्वेस्ट फ़ेल होती है, तो claude auth login चलाएँ और दोबारा कोशिश करें। ऐसा हो सकता है कि सेव किया गया लॉगिन मौजूद हो, फिर भी अगली API रिक्वेस्ट उसे रिफ़्रेश न कर पाए।

होस्ट किए गए ऐप की वैकल्पिक जाँच के लिए Lizard CLI इंस्टॉल करें और अपने प्रोजेक्ट में साइन इन करें। अगर आपको अभी अपना ऐप्लिकेशन डिप्लॉय करना बाकी है, तो पहले Claude Code से डिप्लॉय करें गाइड फ़ॉलो करें।

उदाहरण डाउनलोड करें और डेमो शुरू करें

एक नया फ़ोल्डर बनाएँ और छह फ़ाइलें डाउनलोड करें। चलाने से पहले उन्हें पढ़ लें। डेमो सिर्फ़ GET रिक्वेस्ट लेता है और ग्राहकों का कोई डेटा नहीं रखता।

mkdir claude-deployment-check
cd claude-deployment-check
for file in demo.py collect.py gate.py run.py report.schema.json verify.py; do
  curl --fail --silent --show-error \
    "https://lizard.build/blog-examples/agent-deployment-checks/$file" \
    --output "$file"
done
python3 demo.py --port 8787

वह टर्मिनल चलता रहने दें। दूसरे टर्मिनल में उसी फ़ोल्डर में जाएँ। डेमो में /healthz और /api/quote?quantity=3 उपलब्ध हैं। हर आइटम की कीमत 1,200 सेंट है; तीन आइटम के कोट में currency: USD और total_cents: 3600 आना चाहिए।

ये डेमो रूट हैं। अपने ऐप्लिकेशन के लिए collect.py और gate.py में पाथ और अपेक्षित फ़ील्ड बदलें। कोई छोटा ऑपरेशन चुनें जिसकी यूज़र को सच में ज़रूरत होती है: पहले से डाला गया कोई रिकॉर्ड पढ़ना, कीमत की गणना करना या सेव किया गया कोई डॉक्यूमेंट लाना। जो रूट सिर्फ़ "OK" लौटाता है, वह इन ऑपरेशन की जाँच नहीं कर सकता।

Claude से पूछने से पहले सबूत इकट्ठा करें

python3 collect.py http://127.0.0.1:8787 > evidence.json

कलेक्टर दो रिक्वेस्ट भेजता है, हर एक के लिए पाँच सेकंड का टाइमआउट होता है। यह रीडायरेक्ट, अमान्य JSON और 64 KiB से बड़े रिस्पॉन्स को रिजेक्ट करता है। यह HTTP स्टेटस और अपेक्षित JSON फ़ील्ड, दोनों जाँचता है। यह समय, अपेक्षित मान और जाँच के नतीजे दर्ज करता है; यह रिस्पॉन्स का कोई भी मनमाना टेक्स्ट प्रॉम्प्ट में कॉपी नहीं करता।

यह आख़िरी फ़ैसला तब मायने रखता है जब किसी एंडपॉइंट में यूज़र का लिखा टेक्स्ट हो। किसी सपोर्ट मैसेज या डेटाबेस की row में एजेंट के लिए लिखे गए निर्देश छिपे हो सकते हैं। यह उदाहरण Claude को समझाने के लिए सिर्फ़ मापे गए फ़ील्ड का एक छोटा सेट देता है।

सबूत लिख देने पर कलेक्टर सफलता के साथ बंद होता है, भले ही सबूत किसी फ़ेल जाँच का हो। जॉब पास होगा या नहीं, यह आख़िरी जाँच वाली स्क्रिप्ट तय करती है। अपने ऑटोमेशन में इन दोनों मतलबों को अलग रखें।

स्ट्रक्चर्ड रिपोर्ट माँगें

डाउनलोड की गई फ़ाइलों वाले फ़ोल्डर से यह चलाएँ:

claude --safe-mode -p \
  "Explain the evidence on stdin. Use no tools. Copy its verdict. List the names of failed checks in failed_checks. Give a short summary and one next_step. Do not infer a root cause from HTTP status alone." \
  --tools "" \
  --no-session-persistence \
  --output-format json \
  --json-schema "$(cat report.schema.json)" \
  < evidence.json > claude-result.json

इस रिपोर्ट टास्क के दौरान hooks, plugins और MCP सर्वर जैसे कस्टमाइज़ेशन बंद करने के लिए उदाहरण --safe-mode का इस्तेमाल करता है। यह आपके अकाउंट के मौजूदा लॉगिन से चलता है। अगर आपका इंस्टॉल किया गया वर्ज़न यह फ़्लैग नहीं पहचानता, तो उसका help आउटपुट देखें।

Claude के रिस्पॉन्स में एक बाहरी result ऑब्जेक्ट होता है। जब आप स्कीमा देते हैं, तो रिपोर्ट structured_output के अंदर होती है। बाहरी ऑब्जेक्ट में रन का मेटाडेटा और एक is_error फ़ील्ड भी होता है। सादा JSON रिस्पॉन्स और स्कीमा से बँधा रिस्पॉन्स अलग-अलग काम के लिए हैं; वही फ़ील्ड पार्स करें जो आपकी कमांड ने माँगा था।

स्कीमा चार फ़ील्ड माँगता है:

ये आउटपुट फ़ॉर्मैट प्रोग्रामैटिक तरीके से चलाने के डॉक्यूमेंटेशन में बताए गए हैं। JSON का ढाँचा सही होने से यह साबित नहीं होता कि व्याख्या भी सही है, इसलिए रैपर रिपोर्ट को मापे गए नतीजों से मिलाकर जाँचता है।

पूरी जाँच चलाएँ

run.py ताज़ा सबूत इकट्ठा करता है, 180 सेकंड के प्रोसेस टाइमआउट के साथ Claude को कॉल करता है, रिपोर्ट निकालता है और उसे जाँचता है। हर रन के लिए नई आउटपुट डायरेक्टरी दें:

python3 run.py claude http://127.0.0.1:8787 runs/healthy

डायरेक्टरी में evidence.json, claude-result.json, report.json और stderr.log होते हैं। किसी गड़बड़ी को डीबग करते समय रॉ नतीजा रखें; ऑथेंटिकेशन एरर stdout पर आए नतीजे में दिख सकता है।

रैपर तीन एग्ज़िट कोड इस्तेमाल करता है:

Claude प्रोसेस से कोड 0 का मतलब है कि एजेंट का रन पूरा हुआ। ऐप्लिकेशन के बारे में फ़ैसला रैपर अलग से लेता है। अमान्य रिपोर्ट किसी फ़ेल HTTP जाँच को सफल जॉब में नहीं बदल सकती।

ऐसी गड़बड़ी दोहराएँ जिसे हेल्थ चेक नहीं पकड़ पाता

दूसरे टर्मिनल में दूसरा डेमो शुरू करें:

python3 demo.py --port 8788 --broken

फिर चलाएँ:

python3 run.py claude http://127.0.0.1:8788 runs/broken

दूसरा डेमो अब भी /healthz पर HTTP 200 लौटाता है। लेकिन इसका कोट रूट HTTP 503 लौटाता है। इसलिए सबूत में fail दर्ज होता है और फ़ेल हुई जाँच के रूप में quote आता है। Claude का रिस्पॉन्स वैध हो, तो रैपर एग्ज़िट कोड 1 के साथ बंद होता है।

आप मॉडल को कॉल किए बिना भी HTTP जाँच और वैलिडेशन लॉजिक टेस्ट कर सकते हैं:

python3 verify.py

यह सही और टूटे हुए दोनों डेमो जाँचता है, फिर पक्का करता है कि गेट झूठी सफलता वाली रिपोर्ट और अधूरे सबूत को रिजेक्ट करता है। इसमें Claude क्रेडिट खर्च नहीं होते।

Lizard पर चल रहे ऐप्लिकेशन पर जाँच लगाएँ

अपने प्रोजेक्ट से ऐप्लिकेशन का URL चुनें। Lizard CLI से मौजूदा प्रोजेक्ट का कॉन्टेक्स्ट और सर्विस की स्थिति देखें:

lizard skills get core --json
lizard status --json
lizard ps --project YOUR_PROJECT --json
lizard logs --project YOUR_PROJECT --service YOUR_SERVICE --tail 100 --json

lizard status लोकल फ़ोल्डर का लिंक दिखाता है। lizard ps चुने गए प्रोजेक्ट के लिए सर्विस की स्थिति पढ़ता है। JSON लॉग्स एक सीमित स्नैपशॉट लौटाकर बंद हो जाते हैं; ये सर्विस के लॉग्स लगातार फ़ॉलो नहीं करते।

दोनों रूट की assertions को अपने ऐप्लिकेशन के हिसाब से बदलने के बाद, उसी चेकर के साथ सर्विस का पब्लिक URL इस्तेमाल करें। अगर आप दिया गया डेमो ही होस्ट करते हैं, तो उसे 0.0.0.0 पर bind करें और सर्विस का पोर्ट उसी के हिसाब से कॉन्फ़िगर करें। लोकल उदाहरण 127.0.0.1 पर bind होते हैं।

जब कोई रूट फ़ेल हो, तो दर्ज किए गए जाँच के समय के आसपास के लॉग्स पढ़ें। सिर्फ़ HTTP 503 से यह पता नहीं चलता कि वजह डेटाबेस कनेक्शन थी, कोई डिपेंडेंसी थी या ऐप्लिकेशन कोड। किसी भी लॉग को मॉडल प्रॉम्प्ट में जोड़ने से पहले उसकी समीक्षा करें और संवेदनशील जानकारी हटा दें।

जो ऐप्लिकेशन सेव किए गए डेटा पर निर्भर हैं, उनके लिए किसी जाने-पहचाने रिकॉर्ड के साथ एक टेस्ट जोड़ें। Postgres MCP गाइड सीमित दायरे वाले डेटाबेस एक्सेस के बारे में बताती है, और Redis MCP गाइड Redis से सीमित रीड के बारे में। जाँच के लिए उपयुक्त टेस्ट डेटा और क्रेडेंशियल इस्तेमाल करें।

Headless मोड, ऑथेंटिकेशन और बिना निगरानी वाले जॉब

Headless मोड सिर्फ़ यह बताता है कि आप कमांड कैसे चलाते हैं। यह न तो बिना निगरानी वाला लॉगिन बनाता है और न ही टूल परमिशन हटाता है। शेड्यूल्ड जॉब के लिए रनर पर ऑथेंटिकेशन पहले से तैयार करें और साफ़ टाइमआउट सेट करें।

Claude में --bare भी है, जो सामान्य स्टार्टअप कॉन्टेक्स्ट का ज़्यादातर हिस्सा छोड़ देता है। इसका Anthropic ऑथेंटिकेशन ANTHROPIC_API_KEY या कॉन्फ़िगर किए गए API key helper से होता है; यह सब्सक्रिप्शन वाले OAuth क्रेडेंशियल नहीं पढ़ता। इसलिए अकाउंट लॉगिन वाला हमारा उदाहरण --safe-mode इस्तेमाल करता है। जॉब को CI पर ले जाने से पहले मौजूदा डॉक्यूमेंटेशन देखें, क्योंकि वहाँ ऑथेंटिकेशन सेटअप अलग हो सकता है।

लाइव प्रोग्रेस के लिए Claude --output-format stream-json --verbose सपोर्ट करता है। हर लाइन एक इवेंट है। जब आपको सिर्फ़ एक आख़िरी नतीजा चाहिए, जैसा इस उदाहरण में है, तो सादा json इस्तेमाल करें। किसी स्वतंत्र डिप्लॉयमेंट जाँच के लिए पुरानी बातचीत दोबारा शुरू न करें; हर रन में ताज़ा जाँच-नतीजे (observations) इस्तेमाल होने चाहिए।

समस्या का हल

टेस्ट का दायरा और अगला कदम

28 सितंबर 2026 को हमने Python 3.12.10 के साथ लोकल HTTP और रिपोर्ट-वैलिडेशन टेस्ट चलाए। इनमें सही रिस्पॉन्स, टूटा हुआ कोट रूट, झूठी सफलता वाली रिपोर्ट और गायब सबूत शामिल थे। हमने कमांड के फ़्लैग Claude Code 2.1.259, Lizard CLI 4.0.8 और आधिकारिक डॉक्यूमेंटेशन से मिलाकर जाँचे। Claude मॉडल का रिस्पॉन्स इन पूरे किए गए टेस्ट का हिस्सा नहीं था; ऊपर बताया गया रिपोर्ट का व्यवहार डॉक्यूमेंटेशन में दिए आउटपुट कॉन्ट्रैक्ट पर आधारित है। ये सिंथेटिक टेस्ट किसी प्रोडक्शन ऐप्लिकेशन के सही चलने की गारंटी नहीं देते।

JSONL इवेंट्स और अलग आख़िरी रिपोर्ट फ़ाइल वाले इसी पैटर्न के लिए Codex Exec डिप्लॉयमेंट जाँच देखें। अपना ऐप ऑनलाइन लाने के लिए Claude Code डिप्लॉयमेंट गाइड फ़ॉलो करें, फिर उस ऑपरेशन के लिए जाँच जोड़ें जिसकी आपके यूज़र्स को सबसे ज़्यादा ज़रूरत है।