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 [run] [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.
To start a new web application, create a directory named for the appli-
cation. Then from that directory run pak to install the required sup-
porting packs. For example:
pak install 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
db/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 pack-
aged using the Pak utility (see https://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.
See https://embedthis.com/catalog/ for a list of packs.
Migrations are generated code modules that manage portions of the data-
base. 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
db/migrations directory. A migration is given a unique ordered sequence
Controllers are the primary mechanism for responding to client
requests. To generate a controller, run:
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 function-
ality for the database table. Scaffolds are useful to quickly generate
chunks of the application and prototype web pages and actions for man-
aging 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, inte-
ger, string, and text. The migration will use the name "create_scaf-
fold_MODEL" and will be created under the db/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 ser-
vice incoming requests.
In development mode, ESP will automatically compile the relevant por-
tions of the application if the source code is modified. It can intel-
ligently recompile controllers and ESP pages. However, you can also
explicilty recompile portions or the complete appliction via the esp
the filter pathnames are compiled.
To compile the entire application and produce a single combined shared
library file, set the "esp.combine" property in the esp.json file, to
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 run your application:
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
esp generate scaffold model [field:type [, field:type] ...]
esp generate table name model [field:type [, field:type] ...]
esp run 4000
esp mode debug
esp init appName version
Password cipher to use. Set to "md5" or "blowfish".
--database Database provider
Use the specified database provider. Set to "mdb" or "sdb" for
Overwrite existing files. ESP normally will not overwrite exist-
ing files. This is to preserve user changes to previously gener-
Change the current working directory before beginning processing.
Keep intermediate source files in the cache directory. This over-
rides 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 log-
Name[:logLevel]". Level 3 will trace the request and response
Set the ESP application name. Defaults to the name of the direc-
tory containing the application.
Do not update esp.json.
Compile optimized without debug symbols.
Suppress diagnostic trace to the console.
This selects the route by prefix that will be used for the ESP
configuration. If the route prefix does not match, the first
portion of the route pattern is tested against the requested pre-
Generate a controller for a singleton resource instead of a group
of resources. A singleton controller omits a list action.
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, migra-
tions or scaffolds. This is useful to request a plural version of
the model name. Alternatively, specify the model name when gener-
ating 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 tra-
ceName[: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 (C) Embedthis Software. Embedthis ESP is a trademark of
Man(1) output converted with