@springtree/eva-cli
v1.27.4
Published
`eva-cli` is a command line tool that switches an EVA app project between customers and targets. It downloads the assets and configuration of the chosen customer from the EVA customer manager and copies them into the project.
Keywords
Readme
eva-cli
:evergreen_tree: Purpose
eva-cli is a command line tool that switches an EVA app project between
customers and targets. It downloads the assets and configuration of the chosen
customer from the EVA customer manager and copies them into the project.
| Field | Value | | ---------------- | --------------------------- | | Customer | SpringTree (internal tool) | | Project | EVA | | Production owner | To be assigned |
:seedling: Getting started
Installation
You can install eva-cli globally or per project.
Globally:
npm install -g @springtree/eva-cli
evaPer project:
npm install @springtree/eva-cli
npx evaAuthentication
The tool uses a GitHub personal access token to make sure that you have access. Set it up once:
Make sure that you are a member of the SpringTree Solutions organization on GitHub.
Create a personal access token with the
read:organdread:userscopes.Store the token:
eva set-token --token=TOKEN_HERE
To make sure that a stored token is still valid, run:
eva verify-tokenProject configuration
Every project that uses the tool needs an eva-cli.json file at its root. Each
key is explained in the eva-cli.json file below.
{
"version": 1,
"assets": {
"appIcon": "src/assets",
"appLogo": "src/assets",
"appSplashScreen": "src/assets",
"appSplashScreenGif": "src/assets",
"colors": "src/theme",
"eva-config": "src/assets/env"
},
"framework": "ionic",
"projectName": "eva-companion-app"
}Usage
When eva-cli.json is in place and your token is stored, run:
eva switchThe tool asks you to pick a customer and a target.
CI setup
In CI you do not run set-token. Run switch:ci instead, with the same flags
as switch. The command reads the token from the EVA_SWITCH_TOKEN
environment variable, or from the --token flag:
eva switch:ci --token=TOKEN_HEREThe eva-cli.json file
The eva-cli.json file tells the tool which project it runs in and which
assets to fetch.
assets key
Each key under assets is the identifier of a project asset in the
customer manager.
The tool uses the key to find the matching asset that was uploaded for the
customer under
https://eva-customer-manager.firebaseapp.com/customers/details/:customerId/:projectId.
The value is the directory where the tool copies the asset. The copied file is
named after the asset id, not after the original file name.
eva-config asset key
The eva-config key is reserved. The tool writes the configuration of the
selected target to it, under the file name eva-config.json.
framework key
One of ionic, angular, flutter, react or xcode. The tool uses it to
collect usage data and for framework-specific behavior in the future.
projectName key
The name of an existing project under projects in the customer manager. The tool uses it to show only the customers of this project.
postSwitchScriptPath key
A relative path to an executable script. The tool runs it after the switch
finished, with eva-cli.json as its argument.
Commands
Usage: eva [options] [command]
Commands:
set-token [options] [args] Sets the github personal access token
switch:ci [options] [args] Switches environment, to be used in a CI environment
switch Switch eva environment interactively
verify-token [options] [args] Verifies the currently saved token or the passed token is validKnown issues
Windows
On Windows the tool can fail with this error:
ps1 cannot be loaded because running scripts is disabled on this machineIf you see it, change the PowerShell execution policy. See this step-by-step guide or the Microsoft documentation on execution policies.
:hammer: Development
Use the Node.js version in .nvmrc (Node 24).
# Install dependencies
npm install
# Compile TypeScript to bin/
npm run build
# Run the compiled entry point and restart on changes
npm start
# Same, with the Node.js inspector attached
npm run debugNOTE:
npm installrefuses package versions that are younger than seven days. See Compliance.
:cool: Technology stack
- TypeScript, compiled with
tsctobin/ - Node.js 24
- commander for the command line interface and enquirer for the interactive prompts
- firebase-admin to read from the EVA customer manager
- configstore to store the GitHub token on the machine
- Published to npm as
@springtree/eva-cli
:twisted_rightwards_arrows: Branch strategy and protection
The default branch is master. There are no other long-lived branches.
The master branch is protected by the organization ruleset. It refuses
direct pushes, force pushes and deletion. All changes go through a pull
request, merged with squash or rebase so that the history stays linear.
Before a pull request can merge:
- the four
supply-chain / *checks (secrets,licences,code,quarantine) must pass - changes to the policy files in
.github/CODEOWNERS(the compliance workflow, CODEOWNERS itself andlicence-exemptions.json) must be reviewed by@springtreesolutions/springtree-admins
:pencil: Commit messages
Commits follow Conventional Commits.
This is more than a convention here: release-please reads the commit messages
on master to decide the next version number and to write the changelog.
A fix: commit makes a patch release, a feat: commit makes a minor release,
and a BREAKING CHANGE: footer makes a major release. chore, ci, docs and
the like release nothing.
:lock: Compliance
This repository is gated by SpringTree's shared supply-chain workflow
(.github/workflows/compliance.yml), which runs four checks on every pull
request and a full-history scan weekly:
| Gate | Refuses |
| ------------ | ------------------------------------------------------- |
| secrets | a credential committed anywhere in the scanned range |
| licences | a dependency whose licence is not on the allow-list |
| code | a code pattern the ruleset classes as a security defect |
| quarantine | missing or incorrect package-cooldown configuration |
A red gate is fixed here, in this repository. What each gate does and which
inputs it takes is documented in
springtree-ci-workflows.
Packages younger than seven days are refused (min-release-age in .npmrc).
That window is a management decision recorded in the secure development
standard, not a local preference — raise it there first.
:mag: Before you push
git config core.hooksPath .githooks # once per clone
brew install gitleaks # once per machineThe hook scans the commits you are about to push and refuses the push when
gitleaks is not installed. It is feedback, not enforcement: --no-verify skips
it and CI does not. Skipping is break-glass.
:up: Deploying
The package is published to npm as @springtree/eva-cli by GitHub Actions using
release-please
(.github/workflows/release.yml). Nothing is published by hand.
- Every merge to
masterupdates a single release pull request with the version bump and changelog since the last release (release-please-config.json, current version in.release-please-manifest.json) - Merging the release pull request creates the tag and GitHub release
- The same workflow then builds and publishes the package under the
latestdist-tag
Pull requests to master are built by .github/workflows/build.yml, which
does not publish.
Publishing uses npm trusted publishing
(OIDC), so there is no npm token. The package has a trusted publisher on
npmjs.com for this repository, workflow release.yml and environment
npm-publish. That GitHub environment only allows deployments from master,
so no other branch can publish.
