Configuration

Files

Configuration values are stored in JSON files. The Pureprofile CLI maintains a global configuration file, usually located at ~/.pureprofile/config.json, and project configuration files, usually at the project's root directory as pureprofile.config.json.

The CLI provides commands for setting and printing config values from project config files and the global CLI config file. See pureprofile config --help or see the documentation for usage of.

Project Configuration File

Each Pureprofile project has a project configuration file, usually at the project's root directory. The following is an annotated pureprofile.config.json file.

{
  // The human-readable name of the app.
  "name": "My App",

  // The project type of the app. The CLI uses this value to determine which
  // commands and command options are available, what to output for help
  // documentation, and what to use for web asset builds and the dev server.
  "type": "angular",

  // The App ID for Appflow.
  "id": "abc123",

  // Configuration object for integrations such as Cordova and Capacitor.
  "integrations": {
    "cordova": {
      ...
    }
  },

  // Hook configuration--see the Hooks section below for details.
  "hooks": {
    ...
  }
}

Environment Variables

The CLI will look for the following environment variables:

• PP_CONFIG_DIRECTORY: The directory of the global CLI config. Defaults to ~/.pureprofile.
• PP_HTTP_PROXY: Set a URL for proxying all CLI requests through. See .
• PP_TOKEN: Automatically authenticates with.

Flags

CLI flags are global options that alter the behavior of a CLI command.

• --help: Instead of running the command, view its help page.
• --verbose: Show all log messages for debugging purposes.
• --quiet: Only show WARN and ERROR log messages.
• --no-interactive: Turn off interactive prompts and fancy outputs. If CI or a non-TTY terminal is detected, the CLI is automatically non-interactive.
• --confirm: Turn on auto-confirmation of confirmation prompts. Careful: the CLI prompts before doing something potentially harmful. Auto-confirming may have unintended results.

Hooks

The CLI can run scripts during certain events, such as before and after builds. To hook into the CLI, the following npm scripts can be used in package.json:

• pureprofile:serve:before: executed before the dev server starts
• pureprofile:serve:after: executed after the dev server is terminated
• pureprofile:build:before: executed before a web asset build begins
• pureprofile:build:after: executed after a web asset build finishes
• pureprofile:capacitor:run:before: executed during pureprofile capacitor run before capacitor open is executed
• pureprofile:capacitor:build:before: executed during pureprofile capacitor build before capacitor open is executed
• pureprofile:capacitor:sync:after: executed during pureprofile capacitor sync after a sync

When using a shell script for any of the hooks, hook context is defined in environment variables prefixed with PP_CLI_HOOK_CTX_.

The following example shows the environment variables that are set for the pureprofile:capacitor:build hook.

PP_CLI_HOOK_CTX_NAME=capacitor:build:before
PP_CLI_HOOK_CTX_BUILD_CORDOVA_ASSETS=true
PP_CLI_HOOK_CTX_BUILD_ENGINE=browser
PP_CLI_HOOK_CTX_BUILD_PROJECT=app
PP_CLI_HOOK_CTX_BUILD_TYPE=angular
PP_CLI_HOOK_CTX_BUILD_VERBOSE=false
PP_CLI_HOOK_CTX_CAPACITOR_APP_ID=io.pureprofile.starter
PP_CLI_HOOK_CTX_CAPACITOR_APP_NAME=pureprofile-starter-app
PP_CLI_HOOK_CTX_CAPACITOR_VERBOSE=false

Hooks can also be defined in pureprofile.config.json. Define a hooks object within the project, where each key is the name of the hook (without the pureprofile: prefix), and the value is a path to a JavaScript file or an array of paths.

In the following example, the file is imported and run during the pureprofile:build:before hook.

"hooks": {
  "build:before": "./scripts/build-before.js"
},

JavaScript hook files should export a single function, which is passed a single argument (ctx) whenever the hook executes.

The argument is the context given to the hook file, which differs from hook to hook and with different invocations.

./scripts/build-before.js:

module.exports = function (ctx) {
  console.log(ctx);
};

Multi-app Projects

Available in CLI 6.2.0+

The Pureprofile CLI supports a multi-app configuration setup, which involves multiple Pureprofile apps and shared code within a single repository, or.

note

These docs give an overview of the multi-app feature of the Pureprofile CLI, but don't really go into details for each framework.

If you're using Angular, please see for examples.

Setup Steps

1. Create a directory and initialize a monorepo (see for full details).

2. Initialize the monorepo as an Pureprofile multi-app project. This will create a multi-app pureprofile.config.json file. See for full details.

   $ pureprofile init --multi-app

3. Use pureprofile start to create Pureprofile apps or pureprofile init to initialize existing apps (see for full details).

Project Structure

In a multi-app project, project structure is flexible. The only requirement is a multi-app pureprofile.config.json file at the root of the repository.

Below is an example setup, where apps in the apps/ directory are separated from the shared code in the lib/ directory. Notice the root pureprofile.config.json file and the monorepo's package.json file.

apps/
├── myApp/
└── myOtherApp/
lib/
pureprofile.config.json
package.json

Config File

In a multi-app project, apps share a single pureprofile.config.json file at the root of the repository instead of each app having their own. The multi-app config file contains the configuration for each app by nesting configuration objects in a projects object. A default app can be specified using defaultProject.

Below is an example file, which corresponds to the file structure above.

{
  "defaultProject": "myApp",
  "projects": {
    "myApp": {
      "name": "My App",
      "integrations": {},
      "type": "angular",
      "root": "apps/myApp"
    },
    "myOtherApp": {
      "name": "My Other App",
      "integrations": {},
      "type": "angular",
      "root": "apps/myOtherApp"
    }
  }
}

When a multi-app project is detected, the Pureprofile CLI will operate under the context of an app configured in the root pureprofile.config.json. Project selection criteria is as follows:

1. If the global CLI option --project is specified, the project is looked up by key in the projects object. For example, --project=myApp will select the myApp project.
2. If the CLI detects it is being run within a project path, configured with the root key, it will select the matched project. For example, using the CLI within the apps/myOtherApp/src directory will select the myOtherApp project.
3. If a defaultProject is specified in pureprofile.config.json, it will select the specified project when the above criteria is not met.

Adding an App

Apps can be registered in a multi-app project either by using pureprofile start to create new apps or pureprofile init to initialize existing apps.

Using pureprofile start

If a multi-app project is detected during pureprofile start, the CLI will add the app configuration to the root pureprofile.config.json file instead of creating a project-specific one.

Dependency installation can be skipped using --no-deps if dependencies are hoisted to the root of the monorepo.

$ cd apps/
$ pureprofile start "My New App" --no-deps

Using pureprofile init

If an app was created in a way other than pureprofile start, for example by using a prebuilt template, use pureprofile init to register the existing app with the multi-app project.

note

Make sure the app doesn't have an existing pureprofile.config.json.

$ cd apps/existing-app/
$ pureprofile init

Advanced Configuration

Overriding the Build

Normally, the CLI runs a hard-coded set of commands based on the project type. For example, the standard web asset build for Angular projects is ng run app:build. The web asset build can be overridden and pureprofile build can continue to be used by utilizing the pureprofile:build npm script. Similarly, the dev server can be overridden by using the pureprofile:serve npm script.

Pay close attention to the flags supplied to the script by the Pureprofile CLI. Irregularities may occur if options are not respected, especially for livereload on devices.

Command Options

Command options can be expressed with environment variables. They are normally set with --opt=value syntax. The naming of these environment variables follows a pattern: start with PP_CMDOPTS_, add the command name (replacing any spaces with underscores), add the option name (replacing any hyphens with underscores), and then uppercase everything. Boolean flags (command-line options that don't take a value) can be set to 1 or 0. Strip the --no- prefix in boolean flags, if it exists (--no-open in pureprofile serve can be expressed with PP_CMDOPTS_SERVE_OPEN=0, for example).

For example, the command options in pureprofile cordova run ios -lc --livereload-port=1234 --host=0.0.0.0 can also be expressed with this series of environment variables:

$ export PP_CMDOPTS_CORDOVA_RUN_LIVERELOAD=1
$ export PP_CMDOPTS_CORDOVA_RUN_CONSOLELOGS=1
$ export PP_CMDOPTS_CORDOVA_RUN_LIVERELOAD_PORT=1234
$ export PP_CMDOPTS_CORDOVA_RUN_HOST=0.0.0.0

If these variables are set in the environment, pureprofile cordova build ios will use new defaults for its options.

Telemetry

The CLI sends usage data to Pureprofile to create a better experience. To disable this functionality, run pureprofile config set -g telemetry false.