CLI का उपयोग

awr कमांड-लाइन टूल किसी AWR प्रोजेक्ट का पूर्ण प्रबंधन एंट्री पॉइंट है: MCP के माध्यम से कोई एजेंट जो कुछ कर सकता है, वह आप अपने टर्मिनल से कर सकते हैं — साथ ही वह प्रोजेक्ट प्रशासन भी जो MCP प्रस्तुत नहीं करता।

इंस्टॉलेशन

दोनों पैकेज चैनल वही Rust CLI और MCP सर्वर इंस्टॉल करते हैं; कोई अलग JavaScript या Python SDK नहीं है:

npm install -g @originoneai/agent-work-runtime@0.5.1
# or, in a Python virtual environment
python -m pip install agent-work-runtime==0.5.1

awr --version और awr-mcp --version से सत्यापित करें।

समर्थित लक्ष्य हैं: macOS 15+ (arm64 और Intel), glibc 2.39+ वाला Linux (Ubuntu 24.04 बेसलाइन, x64 और arm64), और Windows x64। npm लॉन्चर को Node 22.14+ चाहिए और यह optional नेटिव पैकेज पर निर्भर है, इसलिए optional dependencies चालू रखें; PyPI लॉन्चर को Python 3.9+ चाहिए। Linux पर ldd --version | head -n 1 से glibc जाँचें। Git केवल Git-बंधे ऑपरेशन के लिए आवश्यक है; SQLite बंडल है। पहले प्रोजेक्ट का वॉकथ्रू चाहिए तो Quickstart देखें।

हर कमांड की बनावट

दस्तावेज़ीकरण भर में CLI उदाहरण एक साझा उपसर्ग रखते हैं:

awr --project /absolute/project --json <command>

--project प्रोजेक्ट रूट की ओर इशारा करता है; --json stdout को एक मशीन-पठनीय JSON ऑब्जेक्ट पर बदल देता है (विवरण नीचे)। आउटपुट खुद पढ़ते समय --json हटा दें — डिफ़ॉल्ट मानव आउटपुट जानबूझकर सीमित है: status अधिकतम एक वर्तमान सुझाव दिखाता है और ready अधिकतम 10 आइटम सूचीबद्ध करता है।

प्रोजेक्ट कहाँ खड़ा है, यह जाँचना

status आपका पहला पड़ाव है। इसका डिफ़ॉल्ट action व्यू वर्तमान निरंतरता, क्लेम योग्य काम, प्रतीक्षाएँ, वास्तविक बाधाएँ और इतिहास सारांश दिखाता है:

awr --project /absolute/project status --view full --branch main

--view action/full/summary — डिफ़ॉल्ट action है; full पूरी लेगसी संरचना देता है।
--branch NAME_OR_ID — डिफ़ॉल्ट ब्रांच के बजाय किसी ब्रांच को नाम, आंतरिक ID या main से पढ़ें। किसी रीड के लिए ब्रांच चुनना कभी डिफ़ॉल्ट ब्रांच, सत्र, क्लेम या आपका Git चेकआउट नहीं बदलता।

ready उन कार्य-आइटम की सूची देता है जो उठाए जा सकते हैं, डायग्नोस्टिक्स, क्लेम जानकारी और छंटनी संकेतों के साथ। --limit का डिफ़ॉल्ट 10 है और 1 से 100 स्वीकार करता है; --branch यहाँ भी काम करता है:

awr --project /absolute/project ready --limit 25

कार्य-आइटम पढ़ना

work show एक आइटम पूरा दिखाता है — टास्क, स्वीकृति मानदंड, निर्भरताएँ, निर्णय, साक्ष्य और उत्पत्ति (provenance)। --source-sha SHA उसे किसी विशिष्ट स्रोत रिवीज़न पर पढ़ता है; --branch उसे दूसरी ब्रांच पर पढ़ता है:

awr --project /absolute/project work show W-123 --source-sha abc123

search प्रोजेक्ट भर में आइटम खोजता है। क्वेरी टेक्स्ट पोज़िशनल है; --type, --status, --work और --limit परिणामों को सीमित करते हैं:

awr --project /absolute/project search "payment retry" --type work --limit 20

किसी टास्क के लिए कॉन्टेक्स्ट कम्पाइल करना

context compile L1 निष्पादन कॉन्टेक्स्ट — किसी टास्क का बजट-बंधा वर्किंग सेट — पूर्णता, अंतराल, उत्पत्ति और Context हैश के साथ एकत्र करता है:

awr --project /absolute/project context compile --work W-123

ये सभी वैकल्पिक हैं: --session और --detached सत्र बाइंडिंग नियंत्रित करते हैं; --agent, --intent और --budget कम्पाइलेशन को दिशा देते हैं; --goal, --path और --tag दोहराए जा सकते हैं; --source-sha किसी विशिष्ट स्रोत संस्करण के सापेक्ष कम्पाइल करता है; --checkpoint और --after-revision कस्टम बेसलाइन सेट करते हैं और परस्पर अनन्य हैं। --branch ID दूसरी ब्रांच पर सामान्य कॉन्टेक्स्ट बेसलाइन इस्तेमाल करता है — इसका अर्थ branch context से अलग है, जो किसी नामित ब्रांच की फ़ोर्क के बाद की वृद्धि को आपकी डिफ़ॉल्ट ब्रांच बदले बिना कम्पाइल करता है:

awr --project /absolute/project branch context feature-x --work W-123

डिफ़ॉल्ट टेक्स्ट आउटपुट बजट-सीमित निष्पादन कॉन्टेक्स्ट है, जिसमें पूर्ण स्वीकृति मानदंड और कठोर नियम संरक्षित रहते हैं। यदि आवश्यक अंतराल मौजूद हैं, तो JSON परिणाम में ok=false और error.code=ContextIncomplete होता है; यदि कठोर तथ्य बजट से बढ़ जाएँ तो आपको BudgetExceeded मिलता है — कभी भी चुपचाप कटे हुए तथ्य नहीं।

काम को आगे बढ़ाना

कार्य-आइटम work सबकमांड के माध्यम से स्थिति बदलते हैं:

awr --project /absolute/project work progress W-123 \
  --session S-1 --reason "starting implementation" --expected-revision 10

यही बनावट block, unblock, cancel और reopen पर लागू होती है, जिसमें --next-action, --summary और --blocker संबंधित विवरण ले जाते हैं। पूर्णता स्वीकृति मानदंड और साक्ष्य को JSON फ़ाइल से बाँधती है और सफलता पर इस सत्र का क्लेम रिलीज़ करती है:

awr --project /absolute/project work complete W-123 \
  --session S-1 --reason "all checks green" \
  --input /absolute/completion.json --expected-revision 10

इवेंट और साक्ष्य दर्ज करना

event append प्रोजेक्ट लॉग में लिखता है:

awr --project /absolute/project event append \
  --type note --summary "reviewer asked for retry tests" \
  --expected-revision 11

वैकल्पिक फ़्लैग: --work, --session, --branch, --importance (डिफ़ॉल्ट normal), और --payload FILE (JSON मान वाली फ़ाइल, छोड़ने पर {})। डिफ़ॉल्ट आउटपुट ID, प्रकार, छोटा सारांश और संस्करण दिखाता है — यह पेलोड को इको नहीं करता; किसी इवेंट को स्पष्ट रूप से खोलने के लिए event show --full इस्तेमाल करें। आप work.completed जैसे आरक्षित डोमेन इवेंट जाली नहीं बना सकते; वे केवल स्थिति-परिवर्तन कमांड से आते हैं।

evidence add JSON इनपुट फ़ाइल से साक्ष्य दर्ज करता है:

awr --project /absolute/project evidence add \
  --input /absolute/evidence.json --expected-revision 11

इनपुट फ़ील्ड में work_item_key, branch_id, external_key, evidence_type, level, summary, locator, sha256, source_sha, command, scope और verified_at शामिल हैं। सफल लेखन सहेजा गया रिकॉर्ड और एक event_id लौटाता है, लेकिन दर्ज करना निष्पादन नहीं है: validation_basis=caller_supplied_bindings का अर्थ है कि AWR ने आपके सबमिट किए बाइंडिंग संग्रहित किए — न कि उसने आपका कमांड चलाया या व्यावसायिक स्वीकृति पास हुई। evidence show किसी रिकॉर्ड का सारांश पठन दृश्य देता है; यह लेखन रसीद नहीं है।

पथ और आकार के नियम: साक्ष्य इनपुट और इवेंट पेलोड में सापेक्ष पथ --project रूट के सापेक्ष हल होते हैं; पूर्णता इनपुट में सापेक्ष पथ प्रोसेस की वर्तमान डायरेक्टरी के सापेक्ष हल होते हैं, इसलिए ऑटोमेशन में निरपेक्ष पथ इस्तेमाल करें। साक्ष्य इनपुट और इवेंट पेलोड फ़ाइलें 1 MiB तक सीमित हैं, पूर्णता इनपुट 64 KiB तक।

रिवीज़न और आशावादी समवर्ती नियंत्रण (optimistic concurrency)

लेखन --expected-revision R लेते हैं, जहाँ R आपका अभी-अभी देखा गया project_revision है। यदि प्रोजेक्ट आगे बढ़ चुका है, तो लेखन किसी और के काम को चुपचाप ओवरराइट करने के बजाय RevisionConflict के साथ विफल होता है — status से दोबारा पढ़ें और नए रिवीज़न के साथ पुनः प्रयास करें। आउटपुट में तीन संस्करण संख्याएँ दिखती हैं और वे परस्पर विनिमेय नहीं हैं: revision किसी ऑब्जेक्ट का संस्करण है, source_revision स्रोत का संस्करण है, और project_revision प्रोजेक्ट स्थिति का संस्करण है।

यदि कोई लेखन बीच में रुक जाए या आंशिक रूप से लागू हो, तो आगे क्या करना है यह तय करने से पहले प्रस्ताव, इवेंट, सत्र और वर्तमान रिवीज़न जाँचें — प्रोसेस विफलता के बाद अंधाधुंध पुनः प्रयास न करें। दो वर्कस्पेस त्रुटियाँ उल्लेखनीय हैं: WorkspaceConflict (awr workspace से) का अर्थ है कि दोनों पक्षों ने एक ही ट्रैक्ड फ़ाइल संपादित की और कुछ भी ऑटो-मर्ज नहीं हुआ; WorkspaceContended का अर्थ है कि कोई publish या drop लगातार तीन कमिट प्रीएम्प्ट हुआ, और उपाय बस वही कमांड दोबारा चलाना है।

JSON आउटपुट, त्रुटियाँ और एक्ज़िट कोड

--json के साथ, सफल कमांड stdout पर ठीक एक JSON ऑब्जेक्ट प्रिंट करता है। त्रुटियाँ stderr पर टाइप्ड JSON होती हैं:

{
  "code": "RevisionConflict",
  "message": "revision conflict: expected 10, actual 11",
  "details": {"expected": 10, "actual": 11}
}

दोनों स्ट्रीम अलग-अलग पार्स करें — उन्हें कभी 2>&1 से मिलाकर संयुक्त टेक्स्ट पार्स न करें। code और details निर्णयों के लिए मशीन-पठनीय आधार हैं; message इंसानों के लिए है। --json किसी ज्ञात सबकमांड से पहले या बाद में आ सकता है; अज्ञात टॉप-लेवल कमांड के लिए JSON त्रुटि पाने हेतु इसे कमांड से पहले रखें। एक्ज़िट कोड:

0 — सफलता (--help और --version भी)।
1 — डोमेन त्रुटि (stderr पर टाइप्ड त्रुटि), संभवतः stdout पर आंशिक, निरीक्षण योग्य बॉडी के साथ; अनुपलब्ध टॉप-लेवल कमांड के लिए Unsupported भी।
2 — गायब या अमान्य तर्क या अज्ञात नेस्टेड सबकमांड; --json मोड में InvalidInput।

CLI कहाँ समाप्त होती है और MCP कहाँ शुरू होता है

CLI और MCP सर्वर वही डोमेन स्थिति प्रस्तुत करते हैं: साझा कार्य और कॉन्टेक्स्ट टूल के लिए, दोनों एक ही प्रोजेक्ट, ब्रांच चयन, इंडेक्स किए गए स्रोत और पैरामीटर के तहत वही पहचानकर्ता, संस्करण, स्वीकृति मानदंड, निर्भरताएँ, डायग्नोस्टिक्स और अंतराल लौटाते हैं। अंतर रुख़ का है:

CLI पूर्ण प्रोजेक्ट प्रबंधन एंट्री पॉइंट है, और इसके रीड पुनर्निर्मित हो सकने वाले डेटाबेस प्रोजेक्शन (source_refresh) ताज़ा कर सकते हैं।
MCP रीड टूल कड़ाई से केवल-पढ़ने योग्य (read_only=true) हैं। यदि स्रोत बदल चुका है, तो MCP रीड ताज़ा करने के बजाय पुराना स्नैपशॉट SourceStale के साथ अस्वीकार कर देता है; awr source reindex चलाएँ और दोबारा पढ़ें।
MCP stdio एजेंट क्लाइंटों के लिए एक निश्चित टूल कैटलॉग प्रस्तुत करता है (साझा HTTP सेवा प्रोजेक्ट डायरेक्टरी टूल जोड़ती है); उस कैटलॉग से परे प्रशासन CLI में ही रहता है।

व्यवहार में, आप सेटअप, प्रशासन, रीइंडेक्सिंग और तात्कालिक जाँच टर्मिनल से चलाते हैं, जबकि आपका एजेंट क्लाइंट सत्र के दौरान MCP टूल कॉल करता है। एजेंट पक्ष के लिए MCP टूल और कुछ गड़बड़ होने पर ट्रबलशूटिंग देखें।