[{"data":1,"prerenderedAt":1262},["ShallowReactive",2],{"page-\u002Fadvanced-input-parsing-user-experience\u002Fstructured-logging-for-cli-apps\u002F":3,"content-directory":1111},{"id":4,"title":5,"body":6,"date":1097,"description":1098,"difficulty":1099,"draft":1100,"extension":1101,"meta":1102,"navigation":189,"path":1103,"seo":1104,"stem":1105,"tags":1106,"updated":1097,"__hash__":1110},"content\u002Fadvanced-input-parsing-user-experience\u002Fstructured-logging-for-cli-apps\u002Findex.md","Structured Logging for CLI Apps",{"type":7,"value":8,"toc":1085},"minimark",[9,22,27,104,108,117,134,162,302,315,319,322,377,384,510,521,525,534,610,637,641,650,740,750,754,761,795,798,802,819,960,971,975,1048,1052,1081],[10,11,12,13,17,18,21],"p",{},"Every CLI eventually needs to say something other than its result: a warning that a config key is deprecated, a debug trace of which file it opened, an error explaining why it stopped. Reaching for ",[14,15,16],"code",{},"print()"," for those messages quietly breaks your tool the moment someone pipes its output into another program. This overview shows how to wire Python's ",[14,19,20],{},"logging"," module into a command-line app so diagnostics go to the right stream, humans get readable output, and machines get parseable records — with verbosity you can dial up or down at runtime.",[23,24,26],"h2",{"id":25},"tldr","TL;DR",[28,29,30,52,59,78,96],"ul",{},[31,32,33,34,36,37,39,40,42,43,46,47,51],"li",{},"Use the ",[14,35,20],{}," module for diagnostics, not ",[14,38,16],{},". Reserve ",[14,41,16],{}," (or ",[14,44,45],{},"stdout",") for the actual ",[48,49,50],"strong",{},"result"," a caller wants to capture.",[31,53,54,55,58],{},"Send ",[48,56,57],{},"logs to stderr, results to stdout",". That one rule keeps your tool composable in pipes and scripts.",[31,60,61,62,65,66,69,70,73,74,77],{},"Learn the four moving parts once: a ",[48,63,64],{},"logger"," creates records, a ",[48,67,68],{},"handler"," routes them, a ",[48,71,72],{},"formatter"," renders them, and a ",[48,75,76],{},"level"," filters them.",[31,79,80,81,90,91,95],{},"Give humans a pretty console (a plain formatter or ",[82,83,87],"a",{"href":84,"rel":85},"https:\u002F\u002Frich.readthedocs.io\u002Fen\u002Fstable\u002Flogging.html",[86],"nofollow",[14,88,89],{},"RichHandler",") and give machines ",[82,92,94],{"href":93},"\u002Fadvanced-input-parsing-user-experience\u002Fstructured-logging-for-cli-apps\u002Fstructured-json-logging-in-python-clis\u002F","structured JSON",".",[31,97,98,99,103],{},"Expose the level with ",[82,100,102],{"href":101},"\u002Fadvanced-input-parsing-user-experience\u002Fstructured-logging-for-cli-apps\u002Fadding-verbose-and-quiet-logging-flags\u002F","verbose and quiet flags"," so users choose how much they see.",[105,106],"inline-diagram",{"name":107},"logging-levels-flow",[23,109,111,113,114,116],{"id":110},"print-versus-logging-for-clis",[14,112,16],{}," versus ",[14,115,20],{}," for CLIs",[10,118,119,121,122,126,127,129,130,133],{},[14,120,16],{}," is fine for the one thing your command produces — the converted file path, the JSON payload, the table of results. It is the wrong tool for everything ",[123,124,125],"em",{},"about"," the run. The moment you ",[14,128,16],{}," a status message, you have mixed diagnostics into the data stream, and a user who runs ",[14,131,132],{},"mycli export > data.json"," finds \"Connecting to database...\" wedged into their JSON.",[10,135,136,138,139,142,143,146,147,150,151,154,155,158,159,95],{},[14,137,20],{}," fixes this by separating three concerns you'd otherwise hand-roll: ",[48,140,141],{},"where"," a message goes (handler), ",[48,144,145],{},"how"," it looks (formatter), and ",[48,148,149],{},"whether"," it shows at all (level). You write one line — ",[14,152,153],{},"log.info(\"connected\")"," — and configuration elsewhere decides the rest. That indirection is exactly what lets the same call site be silent by default, verbose under ",[14,156,157],{},"-v",", and JSON under ",[14,160,161],{},"--log-format=json",[163,164,169],"pre",{"className":165,"code":166,"language":167,"meta":168,"style":168},"language-python shiki shiki-themes github-light github-dark","import logging\n\nlog = logging.getLogger(\"mycli\")\n\ndef export(rows: list[dict]) -> None:\n    log.info(\"exporting %d rows\", len(rows))   # diagnostic -> stderr\n    for row in rows:\n        print(row[\"id\"])                        # result -> stdout\n","python","",[14,170,171,184,191,210,215,241,269,284],{"__ignoreMap":168},[172,173,176,180],"span",{"class":174,"line":175},"line",1,[172,177,179],{"class":178},"szBVR","import",[172,181,183],{"class":182},"sVt8B"," logging\n",[172,185,187],{"class":174,"line":186},2,[172,188,190],{"emptyLinePlaceholder":189},true,"\n",[172,192,194,197,200,203,207],{"class":174,"line":193},3,[172,195,196],{"class":182},"log ",[172,198,199],{"class":178},"=",[172,201,202],{"class":182}," logging.getLogger(",[172,204,206],{"class":205},"sZZnC","\"mycli\"",[172,208,209],{"class":182},")\n",[172,211,213],{"class":174,"line":212},4,[172,214,190],{"emptyLinePlaceholder":189},[172,216,218,221,225,228,232,235,238],{"class":174,"line":217},5,[172,219,220],{"class":178},"def",[172,222,224],{"class":223},"sScJk"," export",[172,226,227],{"class":182},"(rows: list[",[172,229,231],{"class":230},"sj4cs","dict",[172,233,234],{"class":182},"]) -> ",[172,236,237],{"class":230},"None",[172,239,240],{"class":182},":\n",[172,242,244,247,250,253,256,259,262,265],{"class":174,"line":243},6,[172,245,246],{"class":182},"    log.info(",[172,248,249],{"class":205},"\"exporting ",[172,251,252],{"class":230},"%d",[172,254,255],{"class":205}," rows\"",[172,257,258],{"class":182},", ",[172,260,261],{"class":230},"len",[172,263,264],{"class":182},"(rows))   ",[172,266,268],{"class":267},"sJ8bj","# diagnostic -> stderr\n",[172,270,272,275,278,281],{"class":174,"line":271},7,[172,273,274],{"class":178},"    for",[172,276,277],{"class":182}," row ",[172,279,280],{"class":178},"in",[172,282,283],{"class":182}," rows:\n",[172,285,287,290,293,296,299],{"class":174,"line":286},8,[172,288,289],{"class":230},"        print",[172,291,292],{"class":182},"(row[",[172,294,295],{"class":205},"\"id\"",[172,297,298],{"class":182},"])                        ",[172,300,301],{"class":267},"# result -> stdout\n",[10,303,304,305,307,308,311,312,314],{},"The result goes to ",[14,306,45],{},"; the \"exporting N rows\" note goes to ",[14,309,310],{},"stderr"," once you attach a handler there. A caller redirecting ",[14,313,45],{}," still sees the log on their terminal, and a caller redirecting both keeps them in separate files.",[23,316,318],{"id":317},"the-logging-model-logger-handler-formatter-level","The logging model: logger, handler, formatter, level",[10,320,321],{},"Four objects do all the work, and understanding them is the whole game:",[28,323,324,341,361,367],{},[31,325,326,329,330,333,334,258,337,340],{},[48,327,328],{},"Logger"," — what you call (",[14,331,332],{},"logging.getLogger(\"mycli\")","). Loggers form a dotted namespace (",[14,335,336],{},"mycli",[14,338,339],{},"mycli.db",") so you can tune sub-areas independently.",[31,342,343,346,347,350,351,353,354,357,358,360],{},[48,344,345],{},"Handler"," — where records go: a ",[14,348,349],{},"StreamHandler"," to ",[14,352,310],{},", a ",[14,355,356],{},"FileHandler"," to a log file, a ",[14,359,89],{}," for a colorized console. One logger can have several.",[31,362,363,366],{},[48,364,365],{},"Formatter"," — how each record is rendered to text: a timestamp-and-level line for humans, a JSON object for machines.",[31,368,369,372,373,376],{},[48,370,371],{},"Level"," — the threshold. ",[14,374,375],{},"DEBUG \u003C INFO \u003C WARNING \u003C ERROR \u003C CRITICAL",". A record below the effective level is dropped before it's ever formatted.",[10,378,379,380,383],{},"Configure them once at startup, ideally in a single ",[14,381,382],{},"setup_logging()"," function called from your entry point:",[163,385,387],{"className":165,"code":386,"language":167,"meta":168,"style":168},"import logging\nimport sys\n\ndef setup_logging(level: int = logging.WARNING) -> None:\n    handler = logging.StreamHandler(sys.stderr)          # logs -> stderr\n    handler.setFormatter(logging.Formatter(\n        \"%(levelname)s %(name)s: %(message)s\"\n    ))\n    root = logging.getLogger()\n    root.handlers.clear()          # avoid duplicate handlers on re-init\n    root.addHandler(handler)\n    root.setLevel(level)\n",[14,388,389,395,402,406,435,448,453,473,478,489,498,504],{"__ignoreMap":168},[172,390,391,393],{"class":174,"line":175},[172,392,179],{"class":178},[172,394,183],{"class":182},[172,396,397,399],{"class":174,"line":186},[172,398,179],{"class":178},[172,400,401],{"class":182}," sys\n",[172,403,404],{"class":174,"line":193},[172,405,190],{"emptyLinePlaceholder":189},[172,407,408,410,413,416,419,422,425,428,431,433],{"class":174,"line":212},[172,409,220],{"class":178},[172,411,412],{"class":223}," setup_logging",[172,414,415],{"class":182},"(level: ",[172,417,418],{"class":230},"int",[172,420,421],{"class":178}," =",[172,423,424],{"class":182}," logging.",[172,426,427],{"class":230},"WARNING",[172,429,430],{"class":182},") -> ",[172,432,237],{"class":230},[172,434,240],{"class":182},[172,436,437,440,442,445],{"class":174,"line":217},[172,438,439],{"class":182},"    handler ",[172,441,199],{"class":178},[172,443,444],{"class":182}," logging.StreamHandler(sys.stderr)          ",[172,446,447],{"class":267},"# logs -> stderr\n",[172,449,450],{"class":174,"line":243},[172,451,452],{"class":182},"    handler.setFormatter(logging.Formatter(\n",[172,454,455,458,461,464,467,470],{"class":174,"line":271},[172,456,457],{"class":205},"        \"",[172,459,460],{"class":230},"%(levelname)s",[172,462,463],{"class":230}," %(name)s",[172,465,466],{"class":205},": ",[172,468,469],{"class":230},"%(message)s",[172,471,472],{"class":205},"\"\n",[172,474,475],{"class":174,"line":286},[172,476,477],{"class":182},"    ))\n",[172,479,481,484,486],{"class":174,"line":480},9,[172,482,483],{"class":182},"    root ",[172,485,199],{"class":178},[172,487,488],{"class":182}," logging.getLogger()\n",[172,490,492,495],{"class":174,"line":491},10,[172,493,494],{"class":182},"    root.handlers.clear()          ",[172,496,497],{"class":267},"# avoid duplicate handlers on re-init\n",[172,499,501],{"class":174,"line":500},11,[172,502,503],{"class":182},"    root.addHandler(handler)\n",[172,505,507],{"class":174,"line":506},12,[172,508,509],{"class":182},"    root.setLevel(level)\n",[10,511,512,513,516,517,520],{},"Two details matter. Clearing existing handlers makes the function safe to call more than once (tests love this). And configuring the ",[48,514,515],{},"root"," logger means every module that does ",[14,518,519],{},"logging.getLogger(__name__)"," inherits the handler for free — you never wire logging per-module.",[23,522,524],{"id":523},"logs-go-to-stderr-results-go-to-stdout","Logs go to stderr, results go to stdout",[10,526,527,528,530,531,533],{},"This is the rule that makes a CLI behave in a pipeline. ",[14,529,45],{}," is the data channel; ",[14,532,310],{}," is the diagnostics channel. Keep them separate and your tool composes:",[163,535,539],{"className":536,"code":537,"language":538,"meta":168,"style":168},"language-bash shiki shiki-themes github-light github-dark","$ mycli export --format json > out.json      # only results land in the file\nexporting 128 rows                            # log still shows on the terminal\n$ mycli export --format json 2>\u002Fdev\u002Fnull | jq '.[0]'   # drop logs, keep data\n","bash",[14,540,541,566,580],{"__ignoreMap":168},[172,542,543,546,549,551,554,557,560,563],{"class":174,"line":175},[172,544,545],{"class":223},"$",[172,547,548],{"class":205}," mycli",[172,550,224],{"class":205},[172,552,553],{"class":230}," --format",[172,555,556],{"class":205}," json",[172,558,559],{"class":178}," >",[172,561,562],{"class":205}," out.json",[172,564,565],{"class":267},"      # only results land in the file\n",[172,567,568,571,574,577],{"class":174,"line":186},[172,569,570],{"class":223},"exporting",[172,572,573],{"class":230}," 128",[172,575,576],{"class":205}," rows",[172,578,579],{"class":267},"                            # log still shows on the terminal\n",[172,581,582,584,586,588,590,592,595,598,601,604,607],{"class":174,"line":193},[172,583,545],{"class":223},[172,585,548],{"class":205},[172,587,224],{"class":205},[172,589,553],{"class":230},[172,591,556],{"class":205},[172,593,594],{"class":178}," 2>",[172,596,597],{"class":205},"\u002Fdev\u002Fnull",[172,599,600],{"class":178}," |",[172,602,603],{"class":223}," jq",[172,605,606],{"class":205}," '.[0]'",[172,608,609],{"class":267},"   # drop logs, keep data\n",[10,611,612,615,616,618,619,622,623,625,626,628,629,633,634,636],{},[14,613,614],{},"logging.StreamHandler()"," defaults to ",[14,617,310],{},", which is already correct — but be explicit (",[14,620,621],{},"StreamHandler(sys.stderr)",") so no one \"fixes\" it to ",[14,624,45],{}," later. The payoff is that ",[14,627,157],{}," can add as much noise as a user wants without ever corrupting the output another program is parsing. This same discipline underpins ",[82,630,632],{"href":631},"\u002Fadvanced-input-parsing-user-experience\u002Ferror-handling-and-exit-codes\u002F","choosing exit codes and error handling",": errors go to ",[14,635,310],{}," and set a non-zero exit, so scripts can branch on success without scraping text.",[23,638,640],{"id":639},"human-output-versus-machine-output","Human output versus machine output",[10,642,643,644],{},"The same log record should look different depending on who's reading. A developer at an interactive terminal wants a short, colorized line. A log collector wants a JSON object it can index. Decide by asking one question: ",[123,645,646,647,649],{},"is ",[14,648,310],{}," a TTY?",[163,651,653],{"className":165,"code":652,"language":167,"meta":168,"style":168},"import logging\nimport sys\n\ndef choose_formatter() -> logging.Formatter:\n    if sys.stderr.isatty():\n        return logging.Formatter(\"%(levelname)s: %(message)s\")   # human\n    # non-interactive (piped, CI, systemd): switch to structured output\n    from myapp.jsonlog import JsonFormatter\n    return JsonFormatter()\n",[14,654,655,661,667,671,681,689,714,719,732],{"__ignoreMap":168},[172,656,657,659],{"class":174,"line":175},[172,658,179],{"class":178},[172,660,183],{"class":182},[172,662,663,665],{"class":174,"line":186},[172,664,179],{"class":178},[172,666,401],{"class":182},[172,668,669],{"class":174,"line":193},[172,670,190],{"emptyLinePlaceholder":189},[172,672,673,675,678],{"class":174,"line":212},[172,674,220],{"class":178},[172,676,677],{"class":223}," choose_formatter",[172,679,680],{"class":182},"() -> logging.Formatter:\n",[172,682,683,686],{"class":174,"line":217},[172,684,685],{"class":178},"    if",[172,687,688],{"class":182}," sys.stderr.isatty():\n",[172,690,691,694,697,700,702,704,706,708,711],{"class":174,"line":243},[172,692,693],{"class":178},"        return",[172,695,696],{"class":182}," logging.Formatter(",[172,698,699],{"class":205},"\"",[172,701,460],{"class":230},[172,703,466],{"class":205},[172,705,469],{"class":230},[172,707,699],{"class":205},[172,709,710],{"class":182},")   ",[172,712,713],{"class":267},"# human\n",[172,715,716],{"class":174,"line":271},[172,717,718],{"class":267},"    # non-interactive (piped, CI, systemd): switch to structured output\n",[172,720,721,724,727,729],{"class":174,"line":286},[172,722,723],{"class":178},"    from",[172,725,726],{"class":182}," myapp.jsonlog ",[172,728,179],{"class":178},[172,730,731],{"class":182}," JsonFormatter\n",[172,733,734,737],{"class":174,"line":480},[172,735,736],{"class":178},"    return",[172,738,739],{"class":182}," JsonFormatter()\n",[10,741,742,743,745,746,749],{},"When ",[14,744,310],{}," is a terminal, render friendly text. When it's redirected — CI, a pipe, a service manager — emit structured records instead. Let a ",[14,747,748],{},"--log-format=json|console"," flag override the guess, because autodetection is a default, not a law. The deep recipe for the machine side lives in the child guide below.",[23,751,753],{"id":752},"the-two-guides-underneath-this-one","The two guides underneath this one",[10,755,756,757,760],{},"This overview stays at the level of ",[123,758,759],{},"how the pieces fit",". Two focused guides carry the implementations:",[28,762,763,777],{},[31,764,765,770,771,776],{},[82,766,767],{"href":93},[48,768,769],{},"Structured JSON logging in Python CLIs"," — emit machine-readable JSON with a stdlib formatter or ",[82,772,775],{"href":773,"rel":774},"https:\u002F\u002Fwww.structlog.org\u002F",[86],"structlog",", attach context fields like a request ID, and switch renderers based on the terminal.",[31,778,779,784,785,258,787,790,791,794],{},[82,780,781],{"href":101},[48,782,783],{},"Adding verbose and quiet logging flags"," — map ",[14,786,157],{},[14,788,789],{},"-vv",", and ",[14,792,793],{},"--quiet"," onto log levels, pick sane defaults, and keep verbose and quiet mutually exclusive.",[10,796,797],{},"Read the flags guide first if you just want users to be able to say \"tell me more\"; read the JSON guide when your logs need to land in a pipeline.",[23,799,801],{"id":800},"a-pretty-console-with-richhandler","A pretty console with RichHandler",[10,803,804,805,809,810,812,813,815,816,818],{},"For interactive use, ",[82,806,808],{"href":84,"rel":807},[86],"Rich"," gives you colorized levels, aligned columns, and syntax-highlighted tracebacks with almost no configuration. Swap the plain ",[14,811,349],{}," for a ",[14,814,89],{}," when ",[14,817,310],{}," is a terminal:",[163,820,822],{"className":165,"code":821,"language":167,"meta":168,"style":168},"import logging\nfrom rich.logging import RichHandler\n\ndef setup_rich_logging(level: int = logging.WARNING) -> None:\n    logging.basicConfig(\n        level=level,\n        format=\"%(message)s\",          # RichHandler adds level + time columns\n        datefmt=\"[%X]\",\n        handlers=[RichHandler(rich_tracebacks=True, show_path=False)],\n    )\n",[14,823,824,830,843,847,870,875,886,905,924,955],{"__ignoreMap":168},[172,825,826,828],{"class":174,"line":175},[172,827,179],{"class":178},[172,829,183],{"class":182},[172,831,832,835,838,840],{"class":174,"line":186},[172,833,834],{"class":178},"from",[172,836,837],{"class":182}," rich.logging ",[172,839,179],{"class":178},[172,841,842],{"class":182}," RichHandler\n",[172,844,845],{"class":174,"line":193},[172,846,190],{"emptyLinePlaceholder":189},[172,848,849,851,854,856,858,860,862,864,866,868],{"class":174,"line":212},[172,850,220],{"class":178},[172,852,853],{"class":223}," setup_rich_logging",[172,855,415],{"class":182},[172,857,418],{"class":230},[172,859,421],{"class":178},[172,861,424],{"class":182},[172,863,427],{"class":230},[172,865,430],{"class":182},[172,867,237],{"class":230},[172,869,240],{"class":182},[172,871,872],{"class":174,"line":217},[172,873,874],{"class":182},"    logging.basicConfig(\n",[172,876,877,881,883],{"class":174,"line":243},[172,878,880],{"class":879},"s4XuR","        level",[172,882,199],{"class":178},[172,884,885],{"class":182},"level,\n",[172,887,888,891,893,895,897,899,902],{"class":174,"line":271},[172,889,890],{"class":879},"        format",[172,892,199],{"class":178},[172,894,699],{"class":205},[172,896,469],{"class":230},[172,898,699],{"class":205},[172,900,901],{"class":182},",          ",[172,903,904],{"class":267},"# RichHandler adds level + time columns\n",[172,906,907,910,912,915,918,921],{"class":174,"line":286},[172,908,909],{"class":879},"        datefmt",[172,911,199],{"class":178},[172,913,914],{"class":205},"\"[",[172,916,917],{"class":230},"%X",[172,919,920],{"class":205},"]\"",[172,922,923],{"class":182},",\n",[172,925,926,929,931,934,937,939,942,944,947,949,952],{"class":174,"line":480},[172,927,928],{"class":879},"        handlers",[172,930,199],{"class":178},[172,932,933],{"class":182},"[RichHandler(",[172,935,936],{"class":879},"rich_tracebacks",[172,938,199],{"class":178},[172,940,941],{"class":230},"True",[172,943,258],{"class":182},[172,945,946],{"class":879},"show_path",[172,948,199],{"class":178},[172,950,951],{"class":230},"False",[172,953,954],{"class":182},")],\n",[172,956,957],{"class":174,"line":491},[172,958,959],{"class":182},"    )\n",[10,961,962,965,966,970],{},[14,963,964],{},"rich_tracebacks=True"," turns an unhandled exception into a readable, source-highlighted panel instead of a wall of monochrome text — a big usability win for the people running your tool. Rich writes to its own console (stderr by default), so the stdout\u002Fstderr split still holds. If your CLI already uses Rich for ",[82,967,969],{"href":968},"\u002Fadvanced-input-parsing-user-experience\u002Finteractive-terminal-ui-with-rich\u002F","progress bars and other terminal UI",", reusing its handler keeps every message visually consistent. Fall back to the plain formatter when output is redirected, so log files stay free of color escape codes.",[23,972,974],{"id":973},"production-notes","Production notes",[28,976,977,991,1009,1027,1036],{},[31,978,979,982,983,986,987,990],{},[48,980,981],{},"Set the level, don't gate at the call site."," Never wrap ",[14,984,985],{},"log.debug(...)"," in ",[14,988,989],{},"if verbose:",". Set the logger level once and let the framework filter — that's the entire point.",[31,992,993,1000,1001,1004,1005,1008],{},[48,994,995,996,999],{},"Don't ",[14,997,998],{},"basicConfig"," inside a library."," If your CLI is also importable, configure logging only in the entry-point\u002F",[14,1002,1003],{},"main()",", never at import time. Libraries should add a ",[14,1006,1007],{},"NullHandler"," and let the application decide.",[31,1010,1011,1014,1015,1018,1019,1022,1023,1026],{},[48,1012,1013],{},"Interpolate lazily."," Write ",[14,1016,1017],{},"log.info(\"got %s rows\", n)",", not ",[14,1020,1021],{},"log.info(f\"got {n} rows\")",". The ",[14,1024,1025],{},"%","-args are only formatted if the record actually passes the level filter.",[31,1028,1029,1035],{},[48,1030,1031,1032,1034],{},"One ",[14,1033,382],{}," call."," Clear handlers before adding new ones so re-initialization (in tests or plugins) doesn't double every line.",[31,1037,1038,1044,1045,1047],{},[48,1039,1040,1041,95],{},"Capture in tests with ",[14,1042,1043],{},"caplog"," pytest's ",[14,1046,1043],{}," fixture records emitted logs so you can assert on level and message without parsing terminal text.",[23,1049,1051],{"id":1050},"related","Related",[28,1053,1054,1061,1066,1070,1076],{},[31,1055,1056,1057],{},"Up: ",[82,1058,1060],{"href":1059},"\u002Fadvanced-input-parsing-user-experience\u002F","Advanced Input Parsing for Python CLIs",[31,1062,1063,1064],{},"Down: ",[82,1065,769],{"href":93},[31,1067,1063,1068],{},[82,1069,783],{"href":101},[31,1071,1072,1073],{},"Sideways: ",[82,1074,1075],{"href":631},"Error handling and exit codes",[31,1077,1072,1078],{},[82,1079,1080],{"href":968},"Interactive terminal UI with Rich",[1082,1083,1084],"style",{},"html pre.shiki code .szBVR, html code.shiki .szBVR{--shiki-default:#D73A49;--shiki-dark:#F97583}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sJ8bj, html code.shiki .sJ8bj{--shiki-default:#6A737D;--shiki-dark:#6A737D}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .s4XuR, html code.shiki .s4XuR{--shiki-default:#E36209;--shiki-dark:#FFAB70}",{"title":168,"searchDepth":186,"depth":186,"links":1086},[1087,1088,1090,1091,1092,1093,1094,1095,1096],{"id":25,"depth":186,"text":26},{"id":110,"depth":186,"text":1089},"print() versus logging for CLIs",{"id":317,"depth":186,"text":318},{"id":523,"depth":186,"text":524},{"id":639,"depth":186,"text":640},{"id":752,"depth":186,"text":753},{"id":800,"depth":186,"text":801},{"id":973,"depth":186,"text":974},{"id":1050,"depth":186,"text":1051},"2026-07-05","Add configurable logging to Python CLIs: wire the logging module for the terminal, emit JSON logs for machines, and map verbose and quiet flags.","intermediate",false,"md",{},"\u002Fadvanced-input-parsing-user-experience\u002Fstructured-logging-for-cli-apps",{"title":5,"description":1098},"advanced-input-parsing-user-experience\u002Fstructured-logging-for-cli-apps\u002Findex",[20,1107,1108,1109],"cli","json","errors","DOAL9zEbchKyiVJLZvugeXWi9xkmmhXIZk1jwRVHdSg",[1112,1115,1118,1121,1124,1127,1130,1133,1136,1139,1141,1144,1147,1150,1153,1156,1159,1160,1163,1166,1169,1172,1175,1178,1181,1184,1187,1190,1193,1196,1199,1202,1205,1208,1211,1214,1217,1220,1223,1226,1229,1232,1235,1238,1241,1244,1247,1250,1253,1256,1259],{"path":1113,"title":1114},"\u002Fabout","About Python CLI Toolcraft",{"path":1116,"title":1117},"\u002Fadvanced-input-parsing-user-experience\u002Fadvanced-argument-validation-strategies","Advanced Argument Validation Strategies",{"path":1119,"title":1120},"\u002Fadvanced-input-parsing-user-experience\u002Fadvanced-argument-validation-strategies\u002Fparsing-nested-json-arguments-in-python-clis","Parsing Nested JSON Args in Python CLIs",{"path":1122,"title":1123},"\u002Fadvanced-input-parsing-user-experience\u002Ferror-handling-and-exit-codes\u002Fchoosing-exit-codes-for-cli-tools","Choosing Exit Codes for CLI Tools",{"path":1125,"title":1126},"\u002Fadvanced-input-parsing-user-experience\u002Ferror-handling-and-exit-codes\u002Ffriendly-error-messages-and-tracebacks","Friendly Error Messages and Tracebacks",{"path":1128,"title":1129},"\u002Fadvanced-input-parsing-user-experience\u002Ferror-handling-and-exit-codes","Error Handling and Exit Codes for CLIs",{"path":1131,"title":1132},"\u002Fadvanced-input-parsing-user-experience\u002Fhandling-configuration-files-env-vars\u002Fconfig-precedence-flags-env-files-defaults","Config Precedence: Flags, Env, Files, Defaults",{"path":1134,"title":1135},"\u002Fadvanced-input-parsing-user-experience\u002Fhandling-configuration-files-env-vars","Handling Config Files and Env Vars in CLIs",{"path":1137,"title":1138},"\u002Fadvanced-input-parsing-user-experience\u002Fhandling-configuration-files-env-vars\u002Floading-yaml-configs-safely-in-cli-apps","Loading YAML configs safely in CLI apps",{"path":1140,"title":1060},"\u002Fadvanced-input-parsing-user-experience",{"path":1142,"title":1143},"\u002Fadvanced-input-parsing-user-experience\u002Finteractive-terminal-ui-with-rich\u002Fadding-progress-bars-and-spinners-to-python-clis","Progress Bars and Spinners for Python CLIs",{"path":1145,"title":1146},"\u002Fadvanced-input-parsing-user-experience\u002Finteractive-terminal-ui-with-rich","Interactive Terminal UI with Rich",{"path":1148,"title":1149},"\u002Fadvanced-input-parsing-user-experience\u002Fshell-completion-for-python-clis\u002Fenabling-tab-completion-in-click-and-typer","Enabling Tab Completion in Click and Typer",{"path":1151,"title":1152},"\u002Fadvanced-input-parsing-user-experience\u002Fshell-completion-for-python-clis","Shell Completion for Python CLIs",{"path":1154,"title":1155},"\u002Fadvanced-input-parsing-user-experience\u002Fshell-completion-for-python-clis\u002Finstalling-shell-completion-for-bash-zsh-fish","Installing Shell Completion for bash, zsh, fish",{"path":1157,"title":1158},"\u002Fadvanced-input-parsing-user-experience\u002Fstructured-logging-for-cli-apps\u002Fadding-verbose-and-quiet-logging-flags","Adding Verbose and Quiet Logging Flags",{"path":1103,"title":5},{"path":1161,"title":1162},"\u002Fadvanced-input-parsing-user-experience\u002Fstructured-logging-for-cli-apps\u002Fstructured-json-logging-in-python-clis","Structured JSON Logging in Python CLIs",{"path":1164,"title":1165},"\u002F","Python CLI Toolcraft",{"path":1167,"title":1168},"\u002Fmodern-python-cli-frameworks-architecture\u002Fcli-startup-performance-and-lazy-loading","CLI Startup Performance and Lazy Loading",{"path":1170,"title":1171},"\u002Fmodern-python-cli-frameworks-architecture\u002Fcli-startup-performance-and-lazy-loading\u002Flazy-loading-subcommands-for-faster-startup","Lazy Loading Subcommands for Faster Startup",{"path":1173,"title":1174},"\u002Fmodern-python-cli-frameworks-architecture\u002Fcli-startup-performance-and-lazy-loading\u002Fprofiling-python-cli-startup-time","Profiling Python CLI Startup Time",{"path":1176,"title":1177},"\u002Fmodern-python-cli-frameworks-architecture\u002Fcommand-line-parsing-with-argparse\u002Fargparse-subparsers-for-subcommands","argparse Subparsers for Subcommands",{"path":1179,"title":1180},"\u002Fmodern-python-cli-frameworks-architecture\u002Fcommand-line-parsing-with-argparse","Command-Line Parsing with argparse",{"path":1182,"title":1183},"\u002Fmodern-python-cli-frameworks-architecture\u002Fcommand-line-parsing-with-argparse\u002Fmigrating-from-argparse-to-typer","Migrating from argparse to Typer",{"path":1185,"title":1186},"\u002Fmodern-python-cli-frameworks-architecture","Python CLI Frameworks and Architecture",{"path":1188,"title":1189},"\u002Fmodern-python-cli-frameworks-architecture\u002Fplugin-architectures-for-extensible-clis","Plugin Architectures for Extensible CLIs",{"path":1191,"title":1192},"\u002Fmodern-python-cli-frameworks-architecture\u002Fstructuring-multi-command-python-clis\u002Fbest-practices-for-python-cli-entry-points","Best practices for Python CLI entry points",{"path":1194,"title":1195},"\u002Fmodern-python-cli-frameworks-architecture\u002Fstructuring-multi-command-python-clis\u002Fhow-to-structure-a-large-python-cli-project","Structuring a Large Python CLI Project",{"path":1197,"title":1198},"\u002Fmodern-python-cli-frameworks-architecture\u002Fstructuring-multi-command-python-clis","Structuring Multi-Command Python CLIs",{"path":1200,"title":1201},"\u002Fmodern-python-cli-frameworks-architecture\u002Fstructuring-multi-command-python-clis\u002Fsharing-state-with-click-context-objects","Sharing State with Click Context Objects",{"path":1203,"title":1204},"\u002Fmodern-python-cli-frameworks-architecture\u002Ftyper-vs-click-when-to-use-each\u002Fbuilding-a-cli-with-subcommands-in-click","Building a CLI with subcommands in Click",{"path":1206,"title":1207},"\u002Fmodern-python-cli-frameworks-architecture\u002Ftyper-vs-click-when-to-use-each","Typer vs Click: When to Use Each",{"path":1209,"title":1210},"\u002Fmodern-python-cli-frameworks-architecture\u002Ftyper-vs-click-when-to-use-each\u002Ftyper-callback-functions-explained","Typer callback functions explained",{"path":1212,"title":1213},"\u002Fproject-setup-dependency-management\u002Fcli-project-scaffolding-with-cookiecutter","CLI Project Scaffolding with Cookiecutter",{"path":1215,"title":1216},"\u002Fproject-setup-dependency-management","Project Setup & Dependency Management",{"path":1218,"title":1219},"\u002Fproject-setup-dependency-management\u002Fmanaging-cli-versioning-changelogs\u002Fautomating-changelogs-with-conventional-commits","Automating Changelogs with Conventional Commits",{"path":1221,"title":1222},"\u002Fproject-setup-dependency-management\u002Fmanaging-cli-versioning-changelogs","Managing CLI Versioning & Changelogs",{"path":1224,"title":1225},"\u002Fproject-setup-dependency-management\u002Fpackaging-python-clis-for-distribution\u002Fbuilding-wheels-and-sdists-for-python-clis","Building Wheels and sdists for Python CLIs",{"path":1227,"title":1228},"\u002Fproject-setup-dependency-management\u002Fpackaging-python-clis-for-distribution","Packaging Python CLIs for Distribution",{"path":1230,"title":1231},"\u002Fproject-setup-dependency-management\u002Fpackaging-python-clis-for-distribution\u002Finstalling-and-distributing-clis-with-pipx","Installing and Distributing CLIs with pipx",{"path":1233,"title":1234},"\u002Fproject-setup-dependency-management\u002Fpackaging-python-clis-for-distribution\u002Fpublishing-a-python-cli-to-pypi","Publishing a Python CLI to PyPI",{"path":1236,"title":1237},"\u002Fproject-setup-dependency-management\u002Fpoetry-workflows-for-cli-development","Poetry Workflows for CLI Development",{"path":1239,"title":1240},"\u002Fproject-setup-dependency-management\u002Fpoetry-workflows-for-cli-development\u002Fpoetry-entry-points-and-scripts-for-clis","Poetry Entry Points and Scripts for CLIs",{"path":1242,"title":1243},"\u002Fproject-setup-dependency-management\u002Fpre-commit-hooks-for-cli-projects","Pre-commit Hooks for CLI Projects",{"path":1245,"title":1246},"\u002Fproject-setup-dependency-management\u002Fpre-commit-hooks-for-cli-projects\u002Fsetting-up-pre-commit-for-python-cli-repos","Setting up pre-commit for Python CLI repos",{"path":1248,"title":1249},"\u002Fproject-setup-dependency-management\u002Fuv-for-python-cli-dependency-management","uv for Python CLI Dependency Management",{"path":1251,"title":1252},"\u002Fproject-setup-dependency-management\u002Fuv-for-python-cli-dependency-management\u002Fuv-init-vs-poetry-init-for-cli-tools","uv init vs poetry init for CLI tools",{"path":1254,"title":1255},"\u002Fproject-setup-dependency-management\u002Fuv-for-python-cli-dependency-management\u002Fuv-tool-install-vs-pipx-for-clis","uv tool install vs pipx for CLIs",{"path":1257,"title":1258},"\u002Fproject-setup-dependency-management\u002Fvirtual-environments-isolation-best-practices","Python CLI Env Isolation Best Practices",{"path":1260,"title":1261},"\u002Fproject-setup-dependency-management\u002Fvirtual-environments-isolation-best-practices\u002Fmanaging-virtual-environments-for-cross-platform-clis","Managing Python CLI Virtual Environments",1783281867196]