Application Frontend service CLI

Application Frontend Command Line Interface (appfront-cli / afctl)

Description

The Application Frontend Command Line Interface (appfront-cli) provides easy access to APIs exposed by Application Frontend service.
It allows you to:
- Sign-in to and sign-out from the Application Frontend service
- Deploy, explore, modify and delete frontend applications and their versions
- Configure dependencies of frontend applications
- See the runtime logs of frontend applications

Application Frontend Command Line Interface is licensed under the Apache License, Version 2.0 - see LICENSE.
The Open Source Legal Notice is part of the package contents.

Prerequisites

- Download and install Node.js (≥22.6.0).

Installation

``
npm install -g @sap/appfront-cli
`

Upgrade

`
npm update -g @sap/appfront-cli
`

Usage

The Application Frontend Command Line Interface supports the following commands:

#### activate

History

| Version | Changes |
|----------|---------------------------------------------|
| v1.0.0 | Added |

`
Activate deployed application version

Usage:
afctl activate APPLICATION VERSION

Arguments:
APPLICATION Name of the deployed application
VERSION Name of the application version
`

#### ai-analyze

History

| Version | Changes |
|----------|----------------------------------------------------------|
| v1.15.0 | Added |

`
Analyze application version logs with AI

Usage:
afctl ai-analyze APPLICATION [VERSION]

Arguments:
APPLICATION Name of the deployed application
VERSION Name of the application version
`

#### config

History

| Version | Changes |
|-----------|---------------------------------------------|
| v1.14.0 | The -e option added |
| v1.12.0 | The -d option added |
| v1.0.0 | Added |

`
Display actual tool configuration or switch/delete configuration profile

Usage:
afctl config [PROFILE] [-d] [-e]

Arguments:
PROFILE Name of the configuration profile
--delete, -d Delete configuration profile
--env, -e Display supported environment variables and their values
`

#### curl

History

| Version | Changes |
|----------|---------------------------------------------|
| v1.0.0 | Added |

`
Execute a request to the current profile API server URI

Usage:
afctl curl [-i] [-X METHOD] [-H HEADER, ...] PATH

Arguments:
-X METHOD HTTP method to use
-H HEADER Custom headers to include in the request
-d DATA Payload to include in the request body, or '@' followed by a file name to read the data from
-i Print response status and headers
PATH Path and query string of the request URL
`

#### delete

History

| Version | Changes |
|-----------|----------------------------------------------------------|
| v1.14.0 | The d alias added |
| v1.5.0 | Prompt before deletion and -f flag added |
| v1.3.0 | Support of version deletion added |
| v1.0.0 | Added |

`
Delete deployed application or application version

Usage:
afctl delete APPLICATION [VERSION] [-f]

Alias:
d

Arguments:
APPLICATION Name of the deployed application
VERSION Name of the application version
--force, -f Force deletion without prompt
`

#### download

History

| Version | Changes |
|----------|----------------------------------------------------------|
| v1.1.2 | Added |

`
Download deployed application

Usage:
afctl download APPLICATION

Arguments:
APPLICATION Name of the deployed application
`

#### init

History

| Version | Changes |
|-----------|-------------------------------------------------------------------|
| v1.14.0 | The --business-service renamed to --business-solution |
| v1.11.0 | The --cdm, --business-service and PATH_TO_APP options added |
| v1.11.0 | The --name and --version arguments are now named |
| v1.8.0 | Added |

`
Initialize application

Usage:
afctl init [PATH_TO_APP [--name APPLICATION] [--version VERSION], ...] [--business-solution BUSINESS_SOLUTION] [--cdm] [-f]

Arguments:
PATH_TO_APP Path to frontend application directory
--name APPLICATION Name of the application
--version VERSION Name of the application version
--business-solution BUSINESS_SOLUTION Name of the application business solution
--cdm Generate cdm.json file
--force, -f Force init with default values
`

#### install

History

| Version | Changes |
|----------|----------------------------------------------------------|
| v1.1.2 | Added |

`
Install CLI plugin

Usage:
afctl install PLUGIN

Arguments:
PLUGIN CLI plugin package name
`

#### list

History

| Version | Changes |
|-----------|----------------------------------------------------------|
| v1.14.0 | The VERSION option added |
| v1.0.0 | Added |

`
List deployed applications or application versions or application version details

Usage:
afctl list [APPLICATION [VERSION]]

Arguments:
APPLICATION Name of the deployed application
VERSION Name of the deployed application version
`

#### login

History

| Version | Changes |
|----------|----------------------------------------------------------|
| v1.7.0 | The --service-key + --sso together option added |
| v1.6.0 | The --service-key option added |
| v1.0.0 | Added |

`
Login with named user

Usage:
afctl login [-a URI] [-u USERNAME] [-p PASSWORD] [--sso | --p12 DER | --key KEY --cert CERT | --service-key SERVICE_KEY] [PROFILE]

Arguments:
--api, -a URI Application Frontend API server URI
--username, -u USERNAME Username
--password, -p PASSWORD Password
--sso Single sign-on login (requires browser)
--p12 DER P12 certificate bundle (--password will be used to open bundle)
--key KEY PEM private key
--cert CERT PEM certificate
--service-key SERVICE_KEY Application Frontend service key
PROFILE Name of the login profile
`

#### logout

History

| Version | Changes |
|----------|----------------------------------------------------------|
| v1.0.0 | Added |

`
Logout from authorization server and remove locally cached user data

Usage:
afctl logout [PROFILE]

Arguments:
PROFILE Name of the configuration profile
`

#### logs

History

| Version | Changes |
|----------|----------------------------------------------------------|
| v1.0.0 | Added |

`
Get logs of application version

Usage:
afctl logs APPLICATION [VERSION]

Arguments:
APPLICATION Name of the deployed application
VERSION Name of the application version
`

#### push

History

| Version | Changes |
|-----------|----------------------------------------------------------|
| v1.14.0 | The p alias added |
| v1.6.0 | The --activate and --no-activate options added |
| v1.0.4 | The --logs option added |
| v1.0.0 | Added |

`
Deploy new or sync changes to existing application versions

Usage:
afctl push [PATH_TO_APP, ...] [-c CONFIG] [-l] [-a|-n]

Alias:
p

Arguments:
PATH_TO_APP Path to frontend application directory
--config, -c CONFIG Path to configuration file or valid JSON string
--logs, -l Print deployment logs
--activate, -a Activate versions after deployment
--no-activate, -n Don't activate versions after deployment
`

#### set-log-level

History

| Version | Changes |
|-----------|------------------------------------------------------------|
| v1.14.0 | The sll alias added |
| v1.13.1 | Enhanced to display expiration time when TTL is configured |
| v1.13.0 | Added |

`
Set the log level for a specific application version

Usage:
afctl set-log-level APPLICATION [VERSION] --debug|--error

Alias:
sll

Arguments:
APPLICATION Name of the deployed application
VERSION Name of the application version (defaults to active version)
--debug Set log level to debug (temporarily)
--error Set log level to error

Note: When setting the log level to debug, it is configured temporarily with an expiration time.
The command will display the expiration timestamp when applicable.
`

#### start

History

| Version | Changes |
|----------|---------------------------------------------|
| v1.8.0 | Added |

`
Start deployed application

Usage:
afctl start APPLICATION

Arguments:
APPLICATION Name of the deployed application
`

#### stop

History

| Version | Changes |
|----------|---------------------------------------------|
| v1.8.0 | Added |

`
Stop deployed application

Usage:
afctl stop APPLICATION

Arguments:
APPLICATION Name of the deployed application
`

#### uninstall

History

| Version | Changes |
|----------|----------------------------------------------------------|
| v1.1.2 | Added |

`
Uninstall CLI plugin

Usage:
afctl uninstall PLUGIN

Arguments:
PLUGIN CLI plugin package name
`

$3

In addition to command specific arguments, the following global flags may be passed to CLI:

| Flag | Alias | Description |
|------|-------|-------------|
| --help | -h | Print general CLI or command specific help |
| --verbose | -v | Add tracing information to the output |
| --output FORMAT| -o FORMAT| Output format. FORMAT is one of json or yaml|
| --root | | Allow CLI to run with root user privileges |

Configuration

#### AFCTL_CONFIG
The Application Frontend Command Line Interface creates and uses configuration file, which may be found in $HOME/.afctl/config.yaml. It includes multiple configuration profiles that allow to easily switch between various Application Frontend API servers and users. After successfull login, the configuration file also includes JWT (JSON Web Token) that is used to authenticate the calls of command line interface to Application Frontend service API server. To use configuration file different from default, set AFCTL_CONFIG environment variable
to file path of desired configuration file.

#### AFCTL_COLORS
The Application Frontend Command Line Interface recognizes whether it is printing messages to terminal or not (e.g., output may be piped to file). By default, the messages printed to terminal are colorized using special character sequences (e.g., \u001b[0;90m). If your terminal does not support colors or you would like to explicitly switch off colorization, you can set AFCTL_COLORS to one of the falsy values (false|off|no|0).

#### AFCTL_LOG_LEVEL
The Application Frontend Command Line Interface supports multiple log levels:
- 0 - no logs
- 1 - errors only
- 2 - errors and warnings
- 3 - errors, warnings and information messages
- 5 - verbose logs with all messages (useful for troubleshooting and development).
The log level may be controlled by setting AFCTL_LOG_LEVEL environment variable. The default value is 3. If --verbose global flag is used, the log level is 5 (overrides the value set by environment variable).

#### AFCTL_ACTIVATE
By default, the Application Frontend service activates newly deployed application versions.
The behavior may be changed by:
- push command --activate or --no-activate argument (for single command execution)
- push command --config config.json configuration, where config.json '{"activateVersion":false}' (for command execututions using this configuration file)
- AFCTL_ACTIVATE environment variable (for every command executions)

#### AFCTL_POLLING_MAX_ATTEMPTS
During deployment with push command, there is a polling of deployment status.
By default, there will be 120 attempts to fetch the deployment status. After the threshold
is reached, the push command will fail (while deployment itself may still be in progress).
To support long running deployments for large applications (>100Mb), it is possible to change
the maximum number of polling attempts with AFCTL_POLLING_MAX_ATTEMPTS environment variable.
The value must be positive integer.

#### AFCTL_POLLING_DELAY
During deployment with push command, there is a polling of deployment status.
By default, the delay between polling requests is 2 seconds (2000ms).
To set different delay, it is possible to set AFCTL_POLLING_DELAY environment variable.
The value must be positive integer (in milliseconds).

If multiple options are used, the command argument has a higher priority than
configuration file, and configuration file has higher priority than environment variable.

#### AFCTL_XSAPP_TEMPLATE
By default, the init command either uses the xs-app.json in the current working directory (if it exists) as template for the target xs-app.json or creates a brand new xs-app.json. To specify different path to the file that should serve as template for the target xs-app.json, the AFCTL_XSAPP_TEMPLATE environment variable may be set. The template file content should be valid JSON. The route to serve static content from Application Fronted service will be added to the template, if it's not already exist. All routes pointing to html5-apps-repo-rt service will be changed to point to app-front service instead.

#### AFCTL_MANIFEST_TEMPLATE
By default, the init command either uses the manifest.json in the current working directory (if it exists) as template for the target manifest.json or creates a brand new manifest.json. To specify different path to file that should serve as template for the target manifest.json, the AFCTL_MANIFEST_TEMPLATE environment variable may be set. The template file content should be valid JSON. The application name an version will be added to the template or will replace the relevant values, if they are already present in template.

#### AFCTL_SAVE_ZIP
By default, the push command creates ZIP of ZIPs in memory and deletes it, once command is finished.
To keep generated ZIP and save it to file system, the AFCTL_SAVE_ZIP environment variable may be set to any non-empy and non-falsy value.
In this case apps.zip will be saved to current working directory.

#### AFCTL_TRACE
The path to the file, which will contain the traces of executed command.

Troubleshooting

If you experience unexpected behavior, the execution of command never ends, you see error messages or stack traces in the output - you can run any command with global --verbose or just -v` at the end. This will print trace logs with detailed information about each step in the command execution.

License

Copyright 2024 SAP SE or an SAP affiliate company and Application Frontend Command Line Interface contributors.