Command Line Guide

New project

To generate a new Aspen project:

aspen new {project_name}

This will set up a folder with the files you need to start building an Aspen project.

If you already have a Neo4j database you want to use, use the --database-url option to point to that database:

aspen new {project_name} --database-url {URL to Neo4j database}

By default, new generates a Docker Compose file with a sandbox Neo4j database. To skip generating this file, use the --no-docker option.

aspen new {project_name} --no-docker

Building a project

To build your Aspen project, from inside the project folder, run:

aspen build

If you're outputting to Cypher, Aspen uses batching by default to speed up the database query. To ensure that batching is turned off, use the --no-batch option:

aspen build --no-batch

The build process does the following steps every time:

• Checks to make sure the command is run from an Aspen project.
• Downloads all attached resources specified in manifest.yml.
• Runs the bin/convert script, whose purpose is to define how to convert all the non-Aspen data in the project into Aspen syntax.
• Collects all the narrative, discourse, and grammar files from the src folder into one main Aspen file in the build folder.
• Transpiles the main Aspen file into all of the formats specified in manifest.yml, and stores them in the project's build folder.

Pushing data to Neo4j

⚠️ WARNING: Pushing data to Neo4j using the Aspen CLI will DELETE ALL THE DATA in the database. Never use the Aspen CLI with a production database.

To push the latest Cypher build to a Neo4j database, run:

aspen push

Files longer than a few dozen lines may take some time to run.