The Reclusive Command-Line Interpreter

Just a small lib to help your programs to interpret command line arguments effortlessly.

This project is maintained by reclusivebox

ReclusiveCLI - The Reclusive Command Line Interpreter

This is just a small lib to help your programs to interpret command line arguments effortlessly.


ReclusiveCLI was designed with python3 in mind. To install the latest version, please run:

pip install reclusivecli

You can also try the a specific version:

pip install git+


import reclusivecli
import sys
import json

args = sys.argv
with open("my_program_description.json", "r") as json_file:
    specification = json.loads(

useful_information = reclusivecli.parse_command(specification, args)

ReclusiveCLI Rules


There are some rules to define a valid ReclusiveCLI specification. First of all let’s establish some definitions:


Commands are the main piece of a cli interface, there are possibly 2 types of commands: the main command and the subcommands. The main command is essentially the name of your program (ex: git, firefox), the sub commands are things you add to your specification to direct the user to certain parts of the program (ex: apt install, git commit).

Commands must:


Flags are options that can change the default behavior of your program (ex: rm –recursive, rm -r), flags may take arguments if they indicate it in the specification. Flags can also have abbreviations that can be stacked (ex: ls -alt).

Flags must:

Flags can’t:


Compact ways to pass single flags to commands.

Abbreviations must:

Is a good practice to abbreviate flags that takes arguments with capital letters and the others with lower letters.


Stacks are just a way to pass a lot of flags to a command in a simple way.

Stacks must:

Writing the specification

The ReclusiveCLI 1.0 specification is just a map that describes the cli of your program. To write a good specification you just need to know how to write flags and commands, things like stacks are handled by the RCL Interpreter.


A flag specification takes in three possible attributes:


{	// json example
    "name": "recursive",
    "args": 0,
    "abbreviation": "r"
# yaml example
name: "recursive"
args: 0
abbreviation: 'r'

You don’t need to write the dashes (-) and the double dashes (--) for flags in the specification, only when using the command.

Don’t repeat abbreviations for flags, or only the first will work


A command specification takes in four possible attributes:

Remember: if you use a negative arg number with a subcommand it won’t come back to reevaluate the main command, all the arguments after the subcommand will be passed to it, unless there’s other subcommand.


{	// json example
    "name": "cp",
    "args": -2,
    "flags": [
            "name": "recursive",
            "args": 0,
            "abbreviation": "r"
# yaml example
name: "cp"
args: -2
    name: "recursive"
    args: 0
    abbreviation: 'r'

What ReclusiveCLI gives me?

The return value of the parse_command function is very similar to the specification you give to the interpreter, the only differences are:

Examples for git push origin master:

{	// json example
    "name": "git",
    "flags": [],
    "args": [],
            "name": "push",
            "flags": {},
            "args": ["origin", "master"],
            "subcommand": {}
# yaml example
name: "git"
flags: []
args: []
  name: "commit"
  	message: ["Your Message"]
  args: []
  subcommand: {}

Remember the parse_command function only gives you a python dict, the examples above were only to show what’s gonna be inside this dict.