esp compile [pathFilters...]
esp edit key[=value]
esp generate controller name [action [, action] ...]
esp generate migration description model [field:type ...]
esp generate scaffold model [field:type ...]
esp generate table name model [field:type ...]
esp init [name [version]]
esp migrate [forward|backward|NNN]
esp mode [debug|release|otherMode]
esp role [add|remove] rolename
esp serve [ip]:[port]
esp user [add|compute] username password roles...
esp user [remove|show] username
The esp command generates, manages and runs ESP web applications. It
includes a full HTTP/1.1 web server to host your application and can
generate ESP skeletons, controllers, database tables, and scaffolds.
The esp command will create directories and generate configuration and
source code files that can then be manually edited as required. ESP is
supporting packs. For example:
pak install embedthis/esp-html-skeleton
This will will create a set of directories that have the following
documents - Public client web content
documents/assets - Images and assets
documents/css - Client CSS and Less style sheets
documents/index.esp - Home web page
paks - Extension packs
db - Databases and scripts
generate - Template files used when generating
Other directories will be created as needed:
cache - Cache directory for compiled content
migrations - Databases migration modules
controllers - Server side controllers
src - Server side main source code
Most of these directories are initially empty, but may be used over time.
ESP follows conventions where specific files are stored. This greatly
simplifies configuring a web application.
Packs are modules of functionality for ESP applications that are packaged
using the Pak utility (see https://www.embedthis.com/pak). Packs may depend
on other packs so that installing a top level pack may install other
required packs. For example: generating the "esp-html-skeleton" pack will
also install: esp-mvc, exp-less, and other paks.
Migrations are generated code modules that manage portions of the
database. Migrations are used to create tables, initialize with test data
and optionally destroy tables. Migrations are typically generated and
then hand-edited to include relevant initialization or test data.
Migrations are useful to quickly recreate the database with the required
tables and data.
esp generate migration DESCRIPTION TABLE [field:type ...]
The DESCRIPTION is used to name the migration which is created in the
migrations directory. A migration is given a unique ordered sequence
number and the description is appended to this number. The description is
mapped where spaces are changed to "_" characters. When migrations are
run, they are run in sequence number order.
If field:type values are supplied, the database migration will include
code to create a column for each specified field of the requested type.
esp generate controller NAME [actions...]
This will create a controller of the requested name. It will create a
controller source file in the controllers directory. If action names are
requested, the controller source will define an action method for each
name. You can edit the controller source to meet your needs. It will not
be overwritten unless you specify the --force switch.
A scaffold is a generated controller, database migration, client-side
controller and set of views that provides add, edit and list
functionality for the database table. Scaffolds are useful to quickly
generate chunks of the application and prototype web pages and actions
for managing a database table. To generate a scaffold:
esp generate scaffold MODEL [field:type ...]
This will create a scaffold for the specified database table and will
generate a controller of the same name.
If field:type values are supplied, a database migration will be created
with code to create a column for each specified field of the requested
type. The valid database types are: blob, boolean, date, float, integer,
string, and text. The migration will use the name "create_scaffold_MODEL"
and will be created under the migrations direcvtory.
The scaffold will include an edit action and view page that provides add
and edit capability. The list action and view, provides the ability to
list the table rows and select an entry to edit.
If the --singleton switch is ues, the controller will be generated for a
singleton resource and will not have a list action.
ESP compiles controllers and ESP pages native code shared libraries.
These are then loaded and run by ESP in response to incoming client
requests. Code is compiled only once but can be run many times to service
In development mode, ESP will automatically compile the relevant portions
of the application if the source code is modified. It can intelligently
recompile controllers and ESP pages. However, you can also explicilty
recompile portions or the complete appliction via the esp command.
ESP can recompile everything via:
This will re-compile all ESP resources.
ESP can use the system password database or it can define passwords in
the esp.json or in an application database. To define passwords in the
esp user add username password roles...
To define authentication roles, use:
esp role add abilities...
To compile for a target system of a different architecture, you must
specify the target. To do this, use the -platform switch to specify the
target architecture. Specify the path to the platform directory in the
Appweb source code built for that platform.
esp -platform /home/dev/linux-arm-debug compile
The esp mode command will retrieve and display the "esp.mode" property.
The esp mode debug command will modify the "esp.mode" property and set it
to the "debug" value. The esp release command will set the esp.mode to
To run your application, start the esp command to serve pages:
To clean all generated module files:
Migration files can be run via the esp migrate command. With no other
parameters, the command will run all migrations that have not yet been
applied to the database. You can also use esp migrate forward to apply
apply the next unapplied migration. Similarly esp migrate backward will
reverse the last applied migration. You can also use esp migrate NNN to
migrate forward or backward to a specific migration, where NNN is the
migration sequence number at the start of the migration file name.
esp has the following command usage patterns:
Password cipher to use. Set to "md5" or "blowfish".
Combine compiled ESP assets into a single file. Used when building
--database Database provider
Use the specified database provider. Set to "mdb" or "sdb" for
Overwrite existing files. ESP normally will not overwrite existing
files. This is to preserve user changes to previously generated
Change the current working directory before beginning processing.
Keep intermediate source files in the cache directory. This
overrides the ejs.json "keep" setting.
Define the listening endpoint address. This will be used when
generating an application. The value will be patched into the
generated esp.json configuration file.
Specify a file to log messages. The syntax is: "--log
logName[:logLevel]". Level 3 will trace the request and response
Set the ESP application name. Defaults to the name of the directory
containing the application.
Do not update esp.json.
Compile optimized without debug symbols.
Suppress diagnostic trace to the console.
Target platform configuration to build for and directory containing
esp objects and libraries for the target platform. If a path is
supplied, the specified platform directory is used. Otherwise, esp
searches from the current directory upwards for a parent platform
Display the route table to the console.
Use static linking when building ESP applications. This causes esp
to create archive libraries instead of shared libraries.
Compile for debug with symbols.
Override the database table name when generating tables, migrations
or scaffolds. This is useful to request a plural version of the
model name. Alternatively, specify the model name when generating
the scaffold, table or migration with the desired plural suffix.
For example: "-s" or "-ies".
Specify a file for trace messages. The syntax is: "--trace
traceName[:traceLevel]". Level 3 will trace the request and
--verbose or -v
Run in verbose mode and trace actions to the console.
--why or -w
Explain why a resource was or was not compiled.
Report bugs to firstname.lastname@example.org.
Copyright © Embedthis Software. Embedthis ESP is a trademark of Embedthis
esp November 2014 ESP(1)
Man(1) output converted with