CLI
Basilisp includes a basic CLI tool which can be used to start a local REPL session, run some code as a string or from a file, or execute the test suite using the builtin PyTest integration.
Configuration
Basilisp exposes all of it’s available configuration options as CLI flags and environment variables, with the CLI flags taking precedence.
All Basilisp CLI subcommands which include configuration note the available configuration options when the -h and --help flags are given.
Generally the Basilisp CLI configuration options are simple passthroughs that correspond to configuration options for the compiler.
Start a REPL Session
Basilisp’s CLI includes a basic REPL client powered using Prompt Toolkit (and optionally colored using Pygments if you installed the pygments extra).
You can start the local REPL client with the following command.
basilisp repl
The builtin REPL supports basic code completion suggestions, syntax highlighting (if Pygments is installed), multi-line editing, and cross-session history.
Note
You can exit the REPL by entering an end-of-file (“EOF”) character by pressing Ctrl+D at your keyboard.
Start an nREPL Session
Basilisp’s CLI incorporates an nREPL server adapted from nbb.
To start the server from the command line use the following command
basilisp nrepl-server
# => nREPL server started on port 50407 on host 127.0.0.1 - nrepl://127.0.0.1:50407
You can then establish a connection from your IDE to the server address.
Run Basilisp Code
You can run Basilisp code from a string or by directly naming a file with the CLI as well.
basilisp run -c '(+ 1 2 3)'
basilisp run path/to/some/file.lpy
Any arguments passed to basilisp run beyond the name of the file or the code string will be bound to the var *command-line-args* as a vector of strings.
If no arguments are provided, *command-line-args* will be nil.
$ basilisp run -c '(println *command-line-args*)' 1 2 3
[1 2 3]
$ basilisp run -c '(println *command-line-args*)'
nil
Run Basilisp as an Application
Python applications don’t have nearly as many constraints on their entrypoints as do Java applications.
Nevertheless, developers may have a clear entrypoint in mind when designing their application code.
In such cases, it may be desirable to take advantage of the computed Python sys.path to invoke your entrypoint.
To do so, you can use the basilisp run -n flag to invoke an namespace directly:
basilisp run -n package.core
When invoking your Basilisp code via namespace name, the specified namespace name will be bound to the var *main-ns* as a symbol.
This allows you to gate code which should only be executed when this namespace is executed as an entrypoint, but would otherwise allow you to require the namespace normally.
(when (= *main-ns* 'package.core)
(start-app))
This approximates the Python idiom of gating execution on import using if __name__ == "__main__":.
This variant of basilisp run also permits users to provide command line arguments bound to *command-line-args* as described above.
Note
Only basilisp run -n binds the value of *main-ns*.
In all other cases, it will be nil.
Run Basilisp Tests
If you installed the PyTest extra, you can also execute your test suite using the Basilisp CLI.
basilisp test
Because Basilisp defers all testing logic to PyTest, you can use any standard PyTest arguments and flags from this entrypoint.
Bootstrap Python Installation
For some installations, it may be desirable to have Basilisp readily importable whenever the Python interpreter is started. You can enable that as described in Bootstrapping:
basilisp bootstrap
If you would like to remove the bootstrapped Basilisp from your installation, you can remove it:
basilisp bootstrap --uninstall