edge-cli

Cross-platform CLI for the Edge API.

Install

Requires Node.js 20+.

npm install -g @youkno/edge-cli

From source (for contributors)

cd edge-cli
yarn install
yarn build
yarn node dist/index.js --help

Configure

Create ~/.edge-api with your product and environment:

PRODUCT=regulars
ENV=prod

Available products: youkno, stash, alleaves, vera, vip, dinamo1948, propatrimonio, campaigns. Each has a bundled API URL, so no BASE_URL is needed unless you want to override it.

If no product is provided (--product or PRODUCT= in .edge-api), edge-cli shows an interactive product selector when running in a TTY.

Config file resolution

.edge-api files are read in order and merged:

1. /etc/edge-api (system-wide)
2. ./.edge-api (project-local)
3. ~/.edge-api (user home)

Authenticate

edge-cli login

This opens your browser to the admin sign-in page. After signing in, tokens are saved to ~/.edge-cli-auth/accounts.json.

Login creates two sessions from the one sign-in: a shell session that drives edge-cli shell, and an API-only session that edge-cli token prints. Token scope is fixed when the session is created and a refresh re-derives it from the session, so a shell token cannot be narrowed afterwards — the second session is what makes an API-only token possible without a second sign-in.

Prefer the API-only token anywhere a token leaves the CLI (Postman, scripts, a colleague's terminal): a --scope shell token can run any shell command your account is allowed to, against whatever environment it was issued for. If you logged in before this existed, edge-cli token will tell you to log in again rather than hand back the shell-capable one.

To sign in as a member of staff of a particular company, pass its client ID (pin): edge-cli --client 101 login. Both sessions are then exchanged for your row in that company, which is where roles such as shell access live once staff accounts are split per company. Without --client you sign in as yourself, as before. Only the flag on the login command counts. CLIENT_ID in .edge-api does not, and the REPL's /login ignores --client: it re-authenticates whatever identity the current session already is, keeping its company when the stored login is email#clientId. So a --client given for shop context never switches identity. The company session is stored beside your own login as email#clientId (for example [email protected]#101), never over it, and becomes the default. edge-cli login:use <email> switches back to yourself. A stored session keeps the identity it was created with, so to change company, log in again with a different --client.

edge-cli login:list          # see saved accounts
edge-cli login:use <email>   # switch default account
edge-cli logout              # logout current account
edge-cli logout <email>      # logout specific account

Commands

# Check connectivity
edge-cli health-check

# Print effective config (product, env, baseUrl, config files)
edge-cli config

# Get an API token (useful for Postman or curl)
edge-cli token                    # API-only token (aud: edge-api)
edge-cli token --scope shell      # also carries edge-shell; can run shell commands
edge-cli token --refresh          # force token refresh
edge-cli token --header           # print as Authorization header

# Run a shell command
edge-cli shell "<command>"

# Run a script file
edge-cli shell script.esh

# Shell with options
edge-cli shell --dry-run "<command>"         # validate without executing
edge-cli shell --validate "<command>"        # syntax check only
edge-cli shell --json "<command>"            # JSON output
edge-cli shell --continue-on-error script.esh
edge-cli shell -v key=value "<command>"      # pass variables

# Upload users CSV
edge-cli upload-users users.csv
edge-cli upload-users -q users.csv           # quiet mode
edge-cli upload-users -l users.csv           # list mode
edge-cli upload-users -p users.csv           # preview mode

# Set/clear default product
edge-cli product:default regulars
edge-cli product:default --clear

Global flags

| Flag | Description | |---|---| | --product <name> | Override product (default from ~/.edge-api) | | --env <env> | prod, devel, or devlocal (default: prod) | | --base-url <url> | Override API URL | | --client <clientId> | Client ID for client-scoped operations; with login, the company to sign in as staff of | | --config-path <path> | Additional config file path |

Help

edge-cli --help
edge-cli <command> --help