Repository navigation
Introduction to the command line tutorial #3076
Description
Activity
Hi @Rowlando13, can I do this?
Sure!
Hello @Rowlando13 , I will like this issue to be assigned to me
I think I can come up with a good tutorial meeting the above requirements
Thank youOk got it
@Rowlando13, Hey, I started a document, but got busy and havent had time to review or edit 🙈 . Shall I upload and @HanslettTheDev can then contribute also?
Sure!
@Rowlando13 Cool, I will put it under docs. Let me know if you want me to move it elsewhere.
@Rowlando13 Can I continue working on his PR?
Yes.
Got it
I'll request your review tomorrowEdit
I'll send it later this week insteadSorry, I couldn't send the update to this pull request earlier. I had an emergency. I look forward to sending an improved version of the existing PR
No problem. There a really deadlines for Pallets projects since everyone is a volunteer.
Note that we do not accept AI generated PRs. Do not use AI in anything you submit to us. If you think the draft PR needs more, perhaps a start would be to comment on it, rather than start writing from scratch again.
- linked a pull request that will close this issueDocs cli update improvement #3173
on Jul 8, 2026 - linked a pull request that will close this issueAdd Intro to command line tutorial #3160
on Jul 8, 2026 - linked a pull request that will close this issueVery short description of exit codes and how to access them #3112
on Jul 8, 2026 Moving @kdeldycke #3160 (comment) here:
@Rowlando13 is this PR a good candidate overall for the Click documentation? This looks way too generic for a CLI framework. Where should we draw the line? I guess we don't need to explain what a computer is right? 😁 So no need to explain what a CLI is? I vote for closing this PR.
I agree that PR is too generic. I get the motivation here, but I think we need to reassess what we need to teach. It should be specific to understanding Click's execution and responsibilities.
Yeah, the PR is way to generic and not of the quality that I would accept. I was attempting to provide feedback to get it there.
I'm thinking more along the lines of the lifecycle/execution model. I did something similar for Flask: https://flask.palletsprojects.com/en/stable/lifecycle/ This helps people understand what Click's responsibilites are and why it works the way it does. I've referred back to that Flask outline regularly, it helps me remember the whole model as a maintainer too.
- The terminal is in charge of how things are displayed.
- Mention the common default and popular terminals: Gnome Terminal, KDE Konsole, Windows Terminal, Mac Terminal, Ghostty, Kitty, WezTerm.
- Click sends special commands to tell the terminal how to move the cursor and output text.
- The terminal starts a shell.
- The shell is in charge of splitting (tokenizing) typed input, and starting a program with arguments.
- Mention the common shells: Bash, Zsh, Fish, PowerShell.
- Avoid using CMD on Windows, it's weird. PowerShell is modern and recommended.
- The command line is split into tokens on spaces. Quotes are used to keep spaces in a token.
*globs,~home, and$env var expansion.- Windows does not handle the above, so Click emulates it by default.
- Environment variables set in the shell are available in Python and Click.
- Relative paths are relative to the shell's current directory.
- Your Click application is started and given the list of tokens from the shell.
- Click takes your application definition and identifies what
@commandfunction to run. - The command's
@optionand@argumentdefinitions are used to turn the shells tokens into the positional and keyword arguments to call Python command function with. - Click first divides up the tokens, then converts them to the appropriate types, then validates them.
- The shell is in charge of how tab completion is displayed and applied. Click is in charge of telling the shell what completions are available.
- Click provides a special
--helpoption by default for each command. This prints out information about the command and its parameters, instead of executing the command. - Click can be customized to behave very dynamically. Therefore, is may still execute parent commands and code in order to arrive at the current completion or help output.
- When the command finishes, Click returns an exit code to the shell. 0 for success, 1 indicates an error, and other values can represent application-specific statuses.
Reacted by Kevin Deldycke- The terminal is in charge of how things are displayed.
Sounds good. I was thinking something similar. This is a good outline.
That lifecycle page from Flask is an excellent template! And @davidism's variant for Click is absolutely answering @Rowlando13 intention, without getting into too much details.
Something @Rowlando13 pointed at #3173 (comment) is about targeting researchers. This is the right angle: I know a bunch of them and how they work. They're too busy in their own domain producing results, papers, posters and talks at conferences that they have no time to invest into their data workflows and software engineering. So everything is a shell script (I am just slightly exaggerating). Helping them structure their work in CLIs with Click is a good approach.
That's how I structure my tutorial at https://kdeldycke.github.io/click-extra/tutorial.html#from-script-to-cli-in-30-seconds . And the best pathway to upgrade from crappy script to cool CLI without the hassle is to rely on
uv's Python file headers (see: https://kdeldycke.github.io/click-extra/tutorial.html#standalone-script) and you get the best of both worlds.So I guess what's left is to synthesize all of this into a proper tutorial to close this issue.
Developers coming to Click docs may or may not have command line experience. The command line is a big subject with a lot of cross platform differences. A tutorial which targets basic things you can do would be very helpful. The goal is the minimal amount to get started.
Requirements