कमांड-लाइन इंटरफ़ेस गाइडलाइंस (2021)

 (clig.dev)
2 पॉइंट द्वारा GN⁺ 2024-02-07 | 1 टिप्पणियां | WhatsApp पर शेयर करें
  • पारंपरिक UNIX दर्शन की आधुनिक पुनर्व्याख्या के रूप में CLI प्रोग्राम डिज़ाइन सिद्धांत और ठोस गाइडलाइंस को एक open source दस्तावेज़ में व्यवस्थित किया गया है, जिसका मुख्य पाठकवर्ग कमांड-लाइन टूल बनाने वाले डेवलपर्स हैं
  • CLI अब सिर्फ़ एक साधारण scripting platform नहीं, बल्कि मानव-केंद्रित text UI के रूप में विकसित हो चुका है, और इस बदलाव के अनुसार डिज़ाइन सिद्धांतों को भी अपडेट किया जाना चाहिए
  • composability और human-friendliness एक-दूसरे के विरोधी नहीं हैं; standard input/output, pipe, exit code जैसी UNIX परंपराओं का पालन करके दोनों एक साथ हासिल किए जा सकते हैं
  • help text, error message, output format, interactivity, configuration system जैसी उन बारीकियों तक के लिए ठोस सिफारिशें दी गई हैं जिन्हें व्यवहारिक काम में अक्सर नज़रअंदाज़ कर दिया जाता है
  • CLI टूल्स की future compatibility और user trust interface stability और analytics transparency पर निर्भर करती है, और यह गाइड उस बेसलाइन को प्रस्तुत करती है

दर्शन (Philosophy)

मानव-केंद्रित डिज़ाइन

  • पारंपरिक UNIX commands मुख्य रूप से दूसरे programs द्वारा उपयोग किए जाने के लिए डिज़ाइन किए गए थे, लेकिन आज अधिकांश CLI मनुष्यों द्वारा सीधे उपयोग किए जाते हैं, इसलिए human-first design आवश्यक है
  • पहले CLI "machine-first" थे, लेकिन अब वे "human-first" text-based UI में विकसित हो चुके हैं

जोड़कर उपयोग किए जा सकने वाले छोटे हिस्से

  • UNIX दर्शन का मूल यह है कि छोटे और सरल programs को जोड़कर बड़े systems बनाए जाएँ, और यह आज भी उतना ही प्रासंगिक है
  • standard stdin/stdout/stderr, signals, और exit codes programs के बीच कनेक्शन सुनिश्चित करते हैं, जबकि JSON अधिक structured data exchange को support करता है
  • software हमेशा किसी बड़े system का हिस्सा बनता है, इसलिए वह अच्छा component बनेगा या नहीं, यह डिज़ाइन चरण में तय होता है

एकरूपता

  • terminal users के हाथ existing conventions के अभ्यस्त होते हैं, इसलिए CLI को मौजूदा patterns का पालन करना चाहिए
  • लेकिन अगर consistency usability को नुकसान पहुँचाए, तो परंपरा को सावधानी से तोड़ा जा सकता है

उपयुक्त मात्रा में जानकारी

  • अगर कोई command कई मिनट तक बिना किसी output के रुकी रहे, तो यह "बहुत कम" जानकारी है; और अगर वह भारी मात्रा में debug logs उगल दे, तो यह "बहुत ज़्यादा" जानकारी है
  • जानकारी की मात्रा का संतुलन इस बात के लिए बेहद महत्वपूर्ण है कि software उपयोगकर्ता की कितनी अच्छी तरह मदद करता है

खोजने की आसानी (Ease of Discovery)

  • GUI स्क्रीन पर सारी functionality दिखा देता है, लेकिन CLI को अक्सर ऐसी चीज़ समझ लिया जाता है जो सिर्फ़ याददाश्त पर निर्भर करती है
  • व्यापक help text, समृद्ध examples, और अगले command के सुझाव जैसी GUI तकनीकों को अपनाकर CLI को भी सीखने में आसान बनाया जा सकता है

संवाद के रूप में CLI

  • CLI का उपयोग बार-बार कोशिश और असफलता के माध्यम से बनने वाली संवादी संरचना रखता है; error correction suggestions, intermediate state display, और जोखिमपूर्ण कार्यों से पहले confirmation जैसी डिज़ाइन तकनीकें इसी विशेषता का उपयोग करती हैं
  • सबसे खराब interaction वह है जो उपयोगकर्ता को असहाय बना दे; सबसे अच्छा वह है जो उपलब्धि का एहसास कराने वाला सुखद आदान-प्रदान बने

मज़बूती (Robustness)

  • software वास्तव में भी, और अनुभव में भी मज़बूत होना चाहिए
  • अप्रत्याशित input को gracefully handle करना, idempotence बनाए रखना, progress बताना, और stack trace को अनावश्यक रूप से न दिखाना इसके मुख्य तत्व हैं
  • जटिल special cases कम करके और चीज़ों को सरल रखकर robustness बढ़ाई जा सकती है

सहानुभूति (Empathy)

  • CLI tools डेवलपर्स के रचनात्मक tools हैं, इसलिए उनका उपयोग आनंददायक होना चाहिए
  • समस्याओं पर पर्याप्त सोच-विचार करके इस तरह डिज़ाइन करें कि उपयोगकर्ता महसूस करे कि tool उसके पक्ष में है

अराजकता (Chaos)

  • terminal की दुनिया असंगतियों से भरी हुई है, लेकिन यही अराजकता मुक्त सृजन का स्रोत भी है
  • "अगर कोई standard productivity या user satisfaction के लिए स्पष्ट रूप से हानिकारक है, तो उस standard को छोड़ दो" — Jef Raskin

गाइडलाइंस — मूल बातें (The Basics)

  • argument parsing library का उपयोग करें: भाषा के अनुसार सुझाई गई libraries में Go(Cobra, cli), Python(Click, Typer, Argparse), Rust(clap), Node(oclif) आदि शामिल हैं
  • सफलता पर exit code 0, और विफलता पर non-zero code लौटाएँ — scripts इसी आधार पर success/failure पहचानती हैं
  • default output stdout पर, और logs/errors जैसे messages stderr पर भेजें

गाइडलाइंस — help (Help)

  • -h या --help flag पर विस्तृत help text दिखाएँ, और यही नियम subcommands पर भी लागू करें
  • बिना arguments के चलाने पर संक्षिप्त help दिखाएँ (description, 1~2 examples, flags की व्याख्या, --help का संकेत शामिल हो)
    • jq को इसका अच्छा implementation example बताया गया है
  • --help / -h / help subcommand जैसे help request के विभिन्न रूपों को support करें
  • help text के शीर्ष पर web documentation link और feedback path दें
  • पहले examples दिखाएँ — और धीरे-धीरे अधिक जटिल use cases तक ले जाने वाली कहानी-जैसी संरचना सुझाई जाती है
  • अक्सर इस्तेमाल होने वाले flags और commands को help text के शीर्ष पर रखें (git की संरचना का संदर्भ दिया गया है)
  • bold headings जैसी formatting का उपयोग करके इसे scan-friendly बनाएँ, लेकिन terminal-independent तरीक़े अपनाएँ
  • जब उपयोगकर्ता गलत input दे, तो उसकी मंशा का अनुमान लगाकर correction suggestion दी जा सकती है — लेकिन auto-execution पर बहुत सावधानी से निर्णय लें
    • गलत input सिर्फ़ typo नहीं बल्कि कोई logical mistake भी हो सकती है, और auto-correction करने पर उस syntax को स्थायी रूप से support करने का बोझ बन जाता है

गाइडलाइंस — दस्तावेज़ (Documentation)

  • web-based documentation दें — searchability और links share करने के लिए यह आवश्यक है
  • terminal-based documentation दें — यह installed version के साथ sync रहती है और offline भी उपलब्ध होती है
  • man page देने पर विचार करें — इसे ronn जैसे tools से generate किया जा सकता है, और npm help ls की तरह subcommand के ज़रिए access उपलब्ध कराने की सिफारिश है

गाइडलाइंस — output (Output)

  • human readability सबसे पहले — TTY की मौजूदगी से तय करें कि output इंसान पढ़ेगा या नहीं
  • text stream UNIX का universal interface है, इसलिए machine-readable output भी support करें
  • अगर human-friendly output pipe compatibility को नुकसान पहुँचाती हो, तो --plain flag के साथ plain text output दें
  • --json flag दिए जाने पर JSON format output support करें
  • सफलता पर output संक्षिप्त रखें, और ज़रूरत न हो तो बिल्कुल न दें — scripts के लिए -q option से output suppress करने का support दें
  • state बदलने पर उपयोगकर्ता को सूचित करें — git push द्वारा remote branch status दिखाना इसका अच्छा उदाहरण है
  • git status की तरह वर्तमान system state आसानी से दिखाएँ और अगले steps भी सुझाएँ
  • रंगों का उपयोग सोच-समझकर करें, और pipe state, NO_COLOR, TERM=dumb, --no-color जैसी स्थितियों में रंग disable करना अनिवार्य है
  • non-TTY environment में animation या spinner न दिखाएँ (CI logs को गंदा होने से बचाने के लिए)
  • emoji या symbols का उपयोग केवल तभी करें जब वे स्पष्टता बढ़ाएँ (yubikey-agent को उदाहरण के रूप में दिया गया है)
  • ऐसी जानकारी जो सिर्फ़ developers समझ सकते हैं, उसे default output से बाहर रखें; verbose mode में ही दिखाएँ
  • stderr को log file की तरह इस्तेमाल न करें — सामान्यतः log level labels (ERR, WARN) छापने से बचें
  • बहुत अधिक output होने पर less जैसे pager के उपयोग पर विचार करें — इसे केवल TTY environment में activate करें और less -FIRX options सुझाए गए हैं

गाइडलाइंस — errors (Errors)

  • अनुमानित errors को मानव-पठनीय messages में फिर से लिखें (उदाहरण: "chmod +w file.txt चलाना आवश्यक है")
  • signal-to-noise ratio बनाए रखें — एक ही प्रकार की errors को एक ही header के तहत समूहित करके दिखाएँ
  • महत्वपूर्ण जानकारी को output के अंत में रखें — लाल text का उपयोग सोच-समझकर और बहुत कम करें
  • अप्रत्याशित error होने पर debug जानकारी और bug report जमा करने का तरीका साथ दें
  • bug report URL को इस तरह बनाएँ कि जानकारी अपने-आप भर जाए और सबमिट करना आसान हो

गाइडलाइंस — arguments और flags (Arguments and Flags)

  • arguments positional होते हैं, जबकि flags नाम-आधारित — arguments की तुलना में flags को प्राथमिकता दें
  • हर flag का पूरा नाम वाला version दें (जैसे -h और --help दोनों support करें)
  • single-character flags को केवल अक्सर इस्तेमाल होने वाले flags तक सीमित रखें
  • जहाँ standard मौजूद हो, वहाँ standard flag names का उपयोग करें (-f/--force, -q/--quiet, -v, --json आदि)
  • default values को अधिकांश users के लिए उपयुक्त रखें
  • arguments या flags न दिए जाने पर prompt के ज़रिए input माँगें, लेकिन non-interactive environment में prompt को force न करें
  • जोखिमपूर्ण कार्यों से पहले confirmation माँगें — जोखिम के स्तर के अनुसार y/n confirmation, dry-run, या सीधे text input की माँग करें
    • जोखिम स्तरों को mild (file deletion), moderate (directory deletion, remote resource change), और severe (पूरे server deletion) में बाँटा गया है
  • file I/O में - के माध्यम से stdin/stdout से पढ़ने/लिखने का support दें (उदाहरण: curl ... | tar xvf -)
  • flags के ज़रिए secret सीधे न लें — --password-file flag या stdin का उपयोग सुझाया गया है (ps output और shell history में leak होने का जोखिम)

गाइडलाइंस — interactivity (Interactivity)

  • prompts और interactive elements केवल तभी दिखाएँ जब stdin एक TTY हो
  • --no-input दिए जाने पर सभी prompts disable कर दें
  • password input के समय echo disable करें (यानी टाइप किया गया input स्क्रीन पर न दिखे)
  • स्पष्ट रूप से बताएँ कि उपयोगकर्ता कभी भी बाहर निकल सकता है — Ctrl-C हमेशा काम करता रहना चाहिए

गाइडलाइंस — subcommands (Subcommands)

  • subcommands के बीच flag names और output formats की consistency बनाए रखें
  • जटिल tools के लिए noun verb या verb noun रूप में दो-स्तरीय subcommand structure का उपयोग करें (उदाहरण: docker container create)
  • अस्पष्ट या मिलते-जुलते नाम वाले subcommands से बचें (जैसे update और upgrade दोनों का साथ उपयोग न करना)

गाइडलाइंस — robustness (Robustness Guidelines)

  • input validation शुरुआती चरण में करें, और गलत data मिलने पर समझने योग्य error के साथ जल्दी exit करें
  • responsiveness, speed से अधिक महत्वपूर्ण है — 100ms के भीतर कुछ न कुछ output दें
  • लंबे समय लेने वाले कार्यों के लिए progress bar दें — Python(tqdm), Go(schollz/progressbar), Node(node-progress) जैसी libraries उपयोग की जा सकती हैं
  • parallel processing में output आपस में न मिले-जुले, इसका ध्यान रखें
  • network timeout सेट करें — default value सहित, ताकि स्थायी waiting से बचा जा सके
  • temporary errors के बाद retry करने पर पिछले state से resume किया जा सके, ऐसी डिज़ाइन करें
  • crash-only design अपनाएँ — cleanup के बिना भी तुरंत exit हो सकने वाली संरचना से idempotence सुनिश्चित करें

गाइडलाइंस — future compatibility (Future-proofing)

  • बदलावों को backward-compatible additive रूप में बनाए रखें
  • compatibility तोड़ने वाले बदलाव से पहले program के भीतर advance warning दिखाएँ
  • मानव-पठनीय output में बदलाव सामान्यतः स्वीकार्य हैं — scripts के लिए --plain और --json उपयोग करने के लिए प्रेरित करें
  • catch-all subcommand से बचें — वरना बाद में उसी नाम का subcommand जोड़ना असंभव हो सकता है
  • subcommand abbreviations को अपने-आप अनुमति न दें — केवल explicit alias ही स्वीकारें, और उन्हें स्थिर रूप से बनाए रखें
  • "time bomb" से बचें — इस तरह बनाएँ कि 20 साल बाद भी काम कर सके, यानी external dependencies को न्यूनतम रखें

गाइडलाइंस — signals और control characters (Signals)

  • Ctrl-C (INT signal) मिलने पर तुरंत exit करें, और cleanup work के लिए timeout सेट करें
  • cleanup के दौरान Ctrl-C दोबारा दबाने पर force exit संभव हो, ऐसी जानकारी दें (Docker Compose example देखें)
  • program को इस मान्यता के साथ डिज़ाइन करें कि वह अधूरे cleanup state में भी शुरू हो सकता है

गाइडलाइंस — configuration (Configuration)

configuration लागू होने की प्राथमिकता (ऊँची → नीची):

  • flags → current shell environment variables → project-level configuration (.env) → user-level configuration → system-wide configuration

configuration प्रकार के अनुसार सिफारिश:

  • हर invocation पर बदलने वाली configuration (debug level, dry-run): flags का उपयोग करें

  • project या machine के अनुसार बदलने वाली configuration (path, colors, HTTP proxy): flags + environment variables का संयोजन

  • पूरे project में साझा configuration (Makefile, package.json प्रकार): version-controlled files का उपयोग

  • XDG Base Directory spec का पालन करें — ~/.config आधारित configuration path की सिफारिश है (yarn, fish, neovim, tmux आदि इसका समर्थन करते हैं)

  • किसी दूसरे program की configuration file को auto-modify करते समय उपयोगकर्ता की सहमति लेना अनिवार्य है

गाइडलाइंस — environment variables (Environment Variables)

  • environment variables execution context के अनुसार बदलने वाले behavior के लिए उपयुक्त हैं
  • नामों में केवल uppercase letters, digits, और underscore का उपयोग करें; नाम digit से शुरू न हो
  • single-line values की सिफारिश है — multiline values से env command के साथ compatibility issues हो सकते हैं
  • NO_COLOR, DEBUG, EDITOR, HTTP_PROXY, SHELL, TMPDIR, HOME, PAGER जैसे सामान्य environment variables को पहले जाँचें
  • project-specific .env file पढ़ने का support देना अच्छा है — लेकिन .env औपचारिक configuration file का विकल्प नहीं है
    • .env की सीमाएँ: version control में शामिल न होना, history न होना, string का single type होना, encoding समस्याओं के प्रति संवेदनशील होना
  • environment variables से secrets न पढ़ें — वे सभी processes तक propagate होते हैं, logs में leak हो सकते हैं, और Docker inspect या systemctl show से उजागर हो सकते हैं
    • secrets केवल credential files, pipes, AF_UNIX sockets, या secret management services के माध्यम से ही लें

गाइडलाइंस — naming (Naming)

  • सरल और याद रखने में आसान शब्दों का उपयोग करें — बहुत सामान्य नाम दूसरे commands से टकरा सकते हैं
  • lowercase और ज़रूरत पड़ने पर केवल dash का उपयोग करें (curl अच्छा उदाहरण है, DownloadURL बुरा उदाहरण)
  • नाम छोटे रखें, लेकिन cd, ls, ps जैसे अत्यधिक छोटे नाम सामान्य utility commands के लिए आरक्षित हैं
  • Docker Compose के पूर्व नाम plum → fig → docker compose में बदलाव का उदाहरण दिखाता है कि typing convenience naming का एक महत्वपूर्ण मानदंड है

गाइडलाइंस — distribution (Distribution)

  • जहाँ संभव हो, single binary के रूप में distribute करें — जैसे PyInstaller का उपयोग
  • अगर single binary संभव न हो, तो platform-native package installer का उपयोग करें
  • uninstall करने का तरीका installation instructions के अंत में स्पष्ट लिखें

गाइडलाइंस — analytics (Analytics)

  • उपयोगकर्ता की सहमति के बिना usage data या crash data न भेजें
  • अगर data collect किया जाता है, तो क्या collect होगा, क्यों, कैसे anonymize किया जाएगा, और कितने समय तक रखा जाएगा — यह सब स्पष्ट रूप से बताएँ
  • default opt-in की सिफारिश की गई है — अगर opt-out model हो, तो first run या website पर स्पष्ट सूचना दें
    • Angular.js (explicit opt-in), Homebrew (Google Analytics, FAQ सार्वजनिक), और Next.js (default-enabled anonymous telemetry) के तीन उदाहरण दिए गए हैं
  • analytics के विकल्प के रूप में web documentation instrumentation, download count tracking, और सीधे user interviews का उपयोग किया जा सकता है

संबंधित पढ़ाई

1 टिप्पणियां

 
GN⁺ 2024-02-07
Hacker News राय

  • आज बहुत से लोग नहीं जानते कि command line क्या है, और उन्हें यह भी दिलचस्पी नहीं है कि इसका इस्तेमाल क्यों करना चाहिए.

    • 1980 के दशक में भी स्थिति ऐसी ही थी, लेकिन आज पहले से कहीं ज़्यादा लोग command line को जानते हैं. इसे CLI (command line interface) का स्वर्ण युग कहा जा सकता है.

  • स्क्रिप्ट में subcommand के मनमाने संक्षेप की अनुमति न दें. उदाहरण के लिए, यदि mycmd install की जगह mycmd ins या mycmd i की अनुमति दी जाए, तो i से शुरू होने वाला नया command जोड़ा नहीं जा सकेगा.

    • स्क्रिप्ट में short arguments के उपयोग से बचना चाहिए. short arguments इंसानों के लिए टाइपिंग कम करने की सुविधा देते हैं, लेकिन स्क्रिप्ट में स्पष्ट रूप से लिखना कम लागत वाला होता है, और read/write ratio को देखते हुए यह अधिक बेहतर है.

  • --dry-run विकल्प पर विचार करें. बिना वास्तविक बदलाव किए कौन-सा काम किया जाएगा यह पहले से दिखाने वाली सुविधा टूल सीखने और यह जाँचने में बहुत उपयोगी है कि जटिल विकल्प सही तरह सेट किए गए हैं या नहीं.

  • जब stdout interactive terminal न हो, तो animation न दिखाएँ. इससे CI log output में progress bar के Christmas tree जैसा बनने से बचा जा सकता है.

    • stdout में कभी भी animation नहीं दिखाना चाहिए. stderr logging, जानकारी देने आदि के लिए है, और stdout को tty है या नहीं, इससे अलग, हमेशा उपयोगी output देना चाहिए.

  • symbols और emoji का उपयोग केवल तब करें जब वे स्पष्टता बढ़ाएँ.

    • symbols और emoji अलग-अलग terminals में एक समान render नहीं हो सकते, और उपयोगकर्ता की पसंद के अनुसार इन पर अलग-अलग प्रतिक्रियाएँ हो सकती हैं, इसलिए इनका बहुत सावधानी से उपयोग करना चाहिए.

  • मौजूदा Unix command line एक ओर "हैरान करने वाली हद तक उपयोगी" है और दूसरी ओर इसमें "design flaws" भी हैं.

    • Unix command line क्यों उपयोगी है, यह C या Rust में वही काम करने में लगने वाले समय के बारे में सोचकर समझा जा सकता है.
    • design flaws इस बात से आते हैं कि command line interface को एक साथ इंसानों और मशीनों, दोनों के पढ़ने योग्य होना पड़ता है. इस समस्या का कोई canonical समाधान नहीं है.

  • जब तक CLI बहुत बड़ा न हो और nesting की ज़रूरत न हो (जैसे aws), ज़्यादातर apps help में सभी options प्रिंट करना और उपयोगकर्ता को less से ज़रूरी चीज़ ढूँढने देना पसंद करते हैं.

  • परंपरागत रूप से UNIX commands इस धारणा के तहत लिखे गए थे कि उनका मुख्य उपयोग दूसरे programs द्वारा किया जाएगा.

    • वास्तव में उनका उद्देश्य interactive login shell के भीतर interactive उपयोग था. इन्हें output बनाने वाले programs और "quiet" text filters में बाँटा गया था, और जटिल programs C में लिखे जाते थे.

  • environment variables से password न पढ़ें.

    • password केवल credential files, pipes, AF_UNIX sockets, secret management services, या अन्य IPC mechanisms के माध्यम से ही लेना चाहिए.

  • CLI guidelines पर सबसे व्यापक किताब Eric Raymond की पुस्तक है.

    • काफ़ी समय बीत चुका है, लेकिन clig.dev को सरसरी तौर पर देखने पर पता चलता है कि समय के साथ राय काफ़ी बदल गई है.