Project configuration
Getting started
Run l init from your project folder. It asks for configuration first, shows a JSON summary, and saves l.config.json after confirmation.
AWS profile (default): production
Project name (billing-service):
AWS resource region (ap-southeast-1):
Lambda configuration
1. Select existing function from AWS
2. Enter function name manually
3. Use a function name prefix
4. Skip Lambda configuration
Choose [1-4] (2): 2
Lambda function name: billing-api
...
Save l.config.json? [Y/n]:
Choose a menu number and press Enter. The project name comes from the existing config, package.json, or folder name. The default region comes from the existing config, AWS_REGION, AWS_DEFAULT_REGION, the selected profile's session, then ap-southeast-1. The wizard's default profile comes from the existing config or default. l init --profile production uses that profile without asking for its name again.
Selecting a function from AWS requires login and lambda:ListFunctions. All result pages are fetched, then names are sorted and displayed. Back returns to the configuration mode menu. If the list is empty or AWS fails, you can choose manual entry, a prefix, or skip.
Manual mode only validates the name format; it does not verify that the function exists. l init does not create or change AWS resources.
Schema version 1
{
"version": 1,
"name": "billing-service",
"region": "ap-southeast-1",
"profile": "production",
"lambda": {
"functionName": "billing-api"
}
}
| Field | Rules |
|---|---|
version | Required; currently only 1 |
name | Required; a nonempty string |
region | Required; a region format such as ap-southeast-1 or us-gov-west-1 |
profile | Optional; defaults to default. 1–64 lowercase letters, digits, underscores, or hyphens; starts with a letter or digit |
lambda | Optional; exactly one of functionName or prefix |
lambda.functionName | 1–64 letters, digits, underscores, or hyphens |
lambda.prefix | 1–64 letters, digits, underscores, or hyphens |
If you choose a prefix, the Lambda section becomes:
{
"lambda": {
"prefix": "billing-"
}
}
The second example is only a lambda snippet; required fields must still be included. Skipping omits the lambda field. Fields outside the schema are rejected. Region validation checks the format, not availability in your AWS account.
con, prn, aux, nul, com1–com9, and lpt1–lpt9 are rejected on every OS to keep profiles portable. See the release notes.Valid AWS function names that cannot be used as local folder names are rejected during pull/push.
Global authentication
You can keep this config with your project source; it only records the profile name. The default session uses ~/.l/session.json, while other profiles use ~/.l/profiles/<profile>/session.json. Logging in to one profile only replaces that profile's session. Older configs without profile still use default, without session migration. See login and sessions. For a complete multi-account setup, see multiple profiles.
l login --profile production
l login --profile staging
l init --profile production
l whoami
l lambda list --profile staging
A profile name is a local l login label, not an AWS CLI profile from ~/.aws/config. AWS_PROFILE does not select an l profile. A missing or invalid session stops the command; there is no fallback to default. The CLI only validates the profile name format in the config, so manual init can run offline.
The config region is the Lambda resource region. The session region is the auth region for AWS Sign-In, refresh, and whoami; they may differ.
Command defaults
Lambda commands search for l.config.json from the current directory upwards, using the nearest file. An invalid file stops the search instead of being silently skipped. l init always creates or updates the config in the current directory.
| Value | Priority |
|---|---|
| Auth profile | --profile → project profile → default |
| Lambda region | --region → project region → profile session region |
| List prefix | --prefix → lambda.prefix → no filter |
| Info name | name argument → lambda.functionName → error if unavailable |
l lambda info
l lambda info another-function --region us-east-1
l lambda list
l lambda list --prefix other-
l lambda list --prefix ""
A configured function name does not filter lambda list; only a prefix supplies a default filter. Lambda commands also work without a config, using the session region and an explicit name for info.
Updates and cancellation
Pull and push use the same config, store code in lambda/<function-name>/, and record ARNs and revisions in .l/state.json. This version has no additional config field for the code folder. Changing profiles does not remove ARN/account checks on sync history. Use separate project folders for different accounts or regions; profiles with the same account identity and region can use the same baseline.
Run l init again to change the project. The wizard asks for update approval and uses old values as defaults. There is no --force or noninteractive mode. Invalid JSON or unsupported config versions must be fixed first.
Answering no does not write a file. Ctrl+C/EOF cancels input. In v2.0.0, writes use a temporary file followed by atomic publication. For a new config, publication fails if another process has already created the destination. For updates, the wizard checks the file contents again before replacing it; this is not an interprocess locking mechanism. Avoid concurrent edits while confirming a save.
The copy still rejects an existing destination, but it is not atomic: another process may read incomplete JSON, and forced termination may leave a partial config. Inspect and fix the JSON if saving is interrupted. A v2.0.0 workaround is available in Termux troubleshooting.
See the command reference and troubleshooting for commands and errors.