Getting Started

Prerequisites

Before installing area51, you need a working Common Lisp implementation. We recommend SBCL (Steel Bank Common Lisp) for its performance and wide compatibility, but any conforming implementation will work.

• SBCL — recommended, available on most platforms
• CCL (Clozure Common Lisp) — good alternative with native threads
• ECL (Embeddable Common Lisp) — compiles to C, ideal for embedding
• ABCL (Armed Bear Common Lisp) — runs on the JVM

Verify your installation by running:

sbcl --version

Install area51

area51 is a single binary with no runtime dependencies. Install it with one command:

curl -fsSL https://raw.githubusercontent.com/gr8distance/area51/main/install.sh | bash

This installs the area51 binary to ~/.local/bin. Make sure it is on your PATH. You can verify the installation:

area51 --version

Create a Project

Scaffold a new Common Lisp project with area51 new. This generates a standard project structure ready for development.

area51 new my-project
cd my-project

The generated structure:

• area51.lisp — project manifest. Declares dependencies and metadata.
• my-project.asd — ASDF system definition. Auto-updated by area51 add / remove.
• src/package.lisp — defines and exports your package symbols.
• src/main.lisp — your application code starts here.

Adding Packages

Add packages with area51 add. This updates both your area51.lisp manifest and .asd system definition automatically.

area51 add alexandria
area51 add my-lib --github user/my-lib
area51 add some-lib --url https://example.com/lib.tar.gz

Then run area51 install to resolve and download all dependencies:

area51 install

This generates an area51.lock file pinning exact versions for reproducible builds. Now you can use the packages in your source files:

(in-package :my-project)

(defun load-config (path)
  (alexandria:read-file-into-string path))

area51 add updates area51.lisp and your .asd file, but it intentionally does not touch src/package.lisp. How you bring symbols into your package is a taste call, so area51 leaves it to you. You have a few idiomatic options:

:import-from

(defpackage #:my-app
  (:use #:cl)
  (:import-from #:alexandria #:iota #:when-let)
  (:import-from #:arrows #:-> #:->>)
  (:export #:main))

Explicit, the most common style in modern Common Lisp code. Anyone reading your code can tell at a glance where every non-CL symbol came from.

:local-nicknames

(defpackage #:my-app
  (:use #:cl)
  (:local-nicknames (#:a #:alexandria))
  (:export #:main))

;; usage: (a:iota 5)

Keep symbols qualified, but avoid typing the full package name on every call.

:use

(defpackage #:my-app
  (:use #:cl #:arrows)
  (:export #:main))

;; usage: (-> 3 (+ 20 30))

Pulls every exported symbol in. Natural for DSL-ish libraries whose symbols read as syntax (arrows, iterate), but generally avoided for large utility libraries like alexandria where silent symbol conflicts can creep in as the library grows.

Or skip package.lisp entirely and use fully-qualified symbols in your code: (alexandria:iota 5).

Interactive Development with SLY/SLIME

area51 repl starts a slynk server with your project already loaded and *package* dropped into the project package. Connect from Emacs with M-x sly-connect and you get a REPL scoped to the project — no .sbclrc or .dir-locals.el setup needed on the Emacs side.

Start the REPL server from your project directory:

area51 repl

Then in Emacs:

M-x sly-connect RET 127.0.0.1 RET 4005 RET

The REPL opens in your project's package, so you can immediately call (main) or any other exported function without qualifying.

• --port N picks a different port if 4005 is taken.
• Ctrl-C in the area51 terminal shuts down cleanly and releases the port, so an immediate restart just works.
• Per-project isolation: only dependencies listed in this project's area51.lock are visible to ASDF in the running sbcl, matching the isolation of area51 run.

Slynk is loaded via ASDF at startup. If it is not already findable on your machine (SLY ships it; (ql:quickload :slynk) also works), you will see a one-line error instead of a hang.

Browsing Packages

Browse and search packages on the web at glensing.dev/packages.

To see what's installed in your current project:

area51 list

Configuration

area51 stores its configuration and cache in your home directory.

Packages are downloaded once and cached here. The Quicklisp index is refreshed automatically every 24 hours. Run area51 clean to clear the entire cache.

Commands Reference

All available area51 commands at a glance.