Sasjs CLI

@sasjs/cli

The SASjs CLI (npm i -g @sasjs/cli, invoked as sasjs) automates compiling, building, and deploying SAS projects. All commands support -t <target> to select a target from sasjsconfig.json.

Targets and auth

• A target = { name, serverUrl, serverType, appLoc }. serverType is one of SAS9, SASVIYA, SASJS.
• Credentials: sasjs add cred (or a local env file). Viya uses client/secret or sasjs auth login (user/pass, no client/secret needed - see below); SAS 9 uses user/pass; SASJS server uses an access token.
• sasjs context manages Viya compute contexts; sasjs add target adds a new target.

Core workflow

sasjs create myapp        # scaffold a new app (templates available)
sasjs compile             # gather macros/services/jobs into per-file build outputs (sasjsbuild/)
sasjs build               # produce deployable artefacts: JSON + .sas per target
sasjs deploy              # deploy compiled/built artefacts to the target server
sasjs cbd                 # compile + build + deploy in one step (-t viya etc.)

Command reference

Conventions

• Test coverage is generated only from a sasjs compile (or sasjs c). It accepts a target (-t <target>), but nothing is deployed to that target - compilation and coverage are fully local/offline, so no server needs to be available or reachable. Missing macro dependencies (e.g. mp_ds2csv.sas) mean @sasjs/core isn't installed - run npm i first.

• Dependencies are declared in doxygen headers: <h4> SAS Macros </h4>, <h4> SAS Files </h4>, <h4> SAS Folders </h4>, and @li item entries - the CLI builds the dependency tree from these.

• The @li list is the compiler's only dependency source: a macro that is called in the code but not declared is not inlined into the build, and the deployed job fails at runtime with Apparent invocation of macro X not resolved. It can still work by accident when another declared macro's own @li chain happens to inline it (transitive resolution) - which breaks as soon as that macro's dependencies change. Declare every macro the code calls, indirect helpers (e.g. mf_getuser.sas) included; when editing an existing service, re-audit the %macro() calls in the body against the @li entries.

• sasjs compile output goes to the sasjsbuild/ folder (git-ignore it); sasjsresults/ holds test/run outputs.

• CI/CD: sasjs cbd -t viya is the standard deploy step; combine with sasjs servicepack deploy for artefact-based releases.

• Exit codes are non-zero on failure - safe for pipelines.

Gotchas

• Run npm i before sasjs cb - macro dependency resolution needs node_modules/@sasjs/core present, and @sasjs/core (and @sasjs/adapter if used) must be listed in package.json.
• Credentials files are per-target: env files named .env.<targetname> (e.g. .env.server) with CLIENT, ACCESS_TOKEN, and REFRESH_TOKEN entries. Never commit them - gitignore .env*.

Viya auth without a client/secret (sasjs auth login)

sasjs auth login -t <target> authenticates with a regular SAS username/password via the OAuth2 password grant against the built-in, secret-less sas.cli public client. No admin-registered OAuth client is needed - the fastest way to get sasjs run/deploy working on dev/demo estates. The password is never stored; the minted token pair is persisted to a local env file (.env.<target>) or ~/.sasjsrc (global) and verified via /identities/users/@currentUser (Logged in as <id> (<name>)). Bare sasjs auth is still an alias for sasjs add cred.

• Token expiry: the CLI silently refreshes via the stored refresh token (works with and without a client/secret), and re-persists the rotated pair - Viya refresh tokens are single-use/rotating, so this persistence is what keeps later invocations working. If refresh fails, re-run sasjs auth login.
• Some estates give sas.cli a short access-token TTL (e.g. 1h); a refresh on most invocations is normal.
• Opaque (non-JWT) tokens are treated as usable - the server is the authority on expiry.
• Limitations: local/LDAP accounts only (no SSO/SAML/MFA estates); password grant must be enabled for sas.cli (default on Viya 3.5+/4); ROPC is deprecated in OAuth 2.1 - use a registered client/secret for CI/production.
• sasjs run 403 on session creation = the account isn't authorised for the configured compute context - set contextName: "SAS Studio compute context" on the target. First run on a cold estate can take many minutes (compute pod spin-up) and may appear to hang.
• Self-signed estates: use --insecure on auth login, or configure httpsAgentOptions on the target.

Limitations

This skill is a static reference for the SASjs CLI - it provides guidance on using the sasjs command-line tool. It does not execute CLI commands, access the filesystem, read credentials, or make network requests. All commands shown are illustrative; the user must run them in their own environment. References to credential files (.env, ~/.sasjsrc) describe where the CLI stores authentication tokens - this skill does not read, write, or access those files itself.

Viya streaming apps (streamConfig.streamWeb)

With streamWeb: true, sasjs web/cbd -t viya deploys the frontend into SAS Files Service: a streaming job at <appLoc>/services/<streamServiceName>.html serves index.html, and assets land in <appLoc>/services/web/.... At build time every asset/script/css URL in the HTML is rewritten to /SASJobExecution?_FILE=<appLoc>/services/web/... and the adapter config element (<sasjs apploc=...>) is stamped with the target appLoc.

Consequence: the app only works when served from the exact appLoc it was deployed against. If the streaming HTML is placed anywhere else (e.g. manually uploaded to a user home folder like /Users/<id>/myapp/...), all rewritten /Public/app/... asset links 404 and the adapter calls the wrong service paths - the page renders with no CSS/JS and no backend. Fix by redeploying. The original build (sasjs cb) has the apploc from the sasjsconfig.json - when the app is deployed as a SAS program, the supplied %let apploc = (runtime value) is swapped with the compiled_apploc (build time value) to allow apps to be dynamically deployed to a given apploc at deploy time.

Verifying a Viya deployment headlessly (no browser)

1. Get a token - prefer the CLI rather than handling credentials directly: sasjs auth login -t <target> takes care of the OAuth flow and token storage. If you need the token for curl anyway, mint it from the public secret-less client (sas.ec) via the OAuth password grant on /SASLogon/oauth/token - see the SAS Viya REST auth docs; do not embed real credentials in scripts or command lines.
2. Fetch the app: GET /SASJobExecution/?_FILE=<appLoc>/services/<name>.html with Authorization: Bearer -> expect 200 and the full index.html. 401 = auth, anything else = not deployed there.
3. Fetch each asset the HTML references. Response tells you what's wrong:
   • 200 with file content -> asset deployed correctly.
   • 202 + a tiny plain-text body (e.g. Parameter Error\nFile error) -> file does not exist at that Drive path (classic appLoc-mismatch symptom). Note _FILE responses can be async: add &_action=wait to get content synchronously.
   • Services: POST /SASJobExecution/?_program=<appLoc>/services/<svc>&_action=wait -> Parameter Error / Unable to get job definition means the service was never deployed as a JES job (files on Drive alone are not enough - only sasjs deploy/cbd/servicepack deploy registers them).