Anatomy - Overview of internals

serverless binary (front door for three distinct CLI programs)

serverless binary serves as an entrance for three independent CLI programs. Initial logic decides which CLI is actually run in current working directory context. Possible options are listed below

1. Serverless Framework CLI

Documented at of which code is hosted in this repository.

See Anatomy of the Serverless Framework CLI

2. (old v1 of) Serverless Components CLI

Deprecated old version of Serverless Components

Documented at serverless/components/blob/v1, with code hosted at serverless/cli

3. Serverless Components CLI

Documented at, with code hosted at serverless/components

Anatomy of the Serverless Framework CLI


Core flow of a process is managed through internal lifecycle engine, for which, internal (core) and external (user-made) plugins register supported CLI commands attributing to them ordered lifecycle events, plus hooks (event listeners) which are invoked when given event is triggered.

Code organization

Internals are configured with following modules.

Note: that each of these modules are considered private, there should be no dependency on them in external packages. Organization of files and internal API is subject to constant changes

Core classes

Located in lib/classes. Core machinery with lifecycle engine internals

Internal plugins

Located in lib/plugins. Register and implement core CLI commands with its events and attaches hooks for registered events


Located in lib/utils. General utils to be used in either core classes or internal plugins

Flow of a CLI process

  1. Setup essentials related to general error handling and eventual debugging (bin/serverless.js#L40-L56)
  2. Setup autocompletion (only if explicitly turned on) (bin/serverless.js#L58-L61)
  3. Propagate eventual analytics requests which weren't successful in previous runs (bin/serverless.js#L64-L66)
  4. Resolve location of eventual service configuration in current working directory (lib/Serverless.js#L40-L42)
  5. Parse CLI arguments (lib/Serverless.js#L67)
  6. (If in service context) Read service configuration (just read, no normalization and variables resolution at this point) (lib/classes/PluginManager.js#L60-L63)
  7. Check whether there's a newer version of a Framework available, and notify user if there is (Serverless.js#L79-L89)
  8. (If in service context) Normalize service configuration by filling defaults and ensuring core structure (no variables resolution yet) (lib/classes/Service.js#L38-L53)
  9. Load all plugins (internal and those installed by user). They configure supported CLI commands, register events for lifecycle engine, and attach hooks to events eventually triggered by lifecycle engine (lib/classes/PluginManager.js#L107-L116
  10. If it's sls --help command, show help and abort (lib/Serverless.js#L108-L110
  11. (If in service context) Populate all variables in service configuration (lib/Serverless.js#L118-L125)
  12. (if in service context) Validate service configuration (lib/Serverless.js#L128
  13. Run lifecycle engine (emit all events that were registered for invoked CLI command) (lib/classes/PluginManager.js#L509-L511)
  14. If execution ended with an error, log it in user friendly way (lib/classes/Error.js#L68-L129)
Go to Github