shell

const { shell } = require("backendjs");

shell.commands.myCommand = function(options) {
   console.log("hello");
   return "continue"
}
// Calling `bksh -my-command` it will run this command.

(static) runFile()

Description:

• Load a module and optionally execute it

Source:

• shell/shell.js, line 225

Example

var { app } = require("backendjs")
app.test = 123;
exports.run = function() {
  console.log("run");
}
exports.newMethod = function() {
  console.log(app.version, "version");
}

// Save into a file a.js and run

  bksh -run-file a.js

// In the shell now it new methods can be executed

   > shell.newMethod()

(static) sendRequest(options)

Description:

• Shell command: sendRequest

  Sends an HTTP request using lib.fetch with optional BackendJS-style API signing, CSRF token bootstrap, custom headers/cookies, and response shaping/formatting.

  Request inputs:

  • Request data is taken from shell.getQuery:
    • If -method is provided (i.e. non-empty), the query becomes postdata
    • If -method is not provided, the query becomes URL query params

  Options:

  • -url <url>: Target URL to request.
  • -method <verb>: HTTP method (e.g. POST, PUT). When set, query data is sent as body (postdata).
  • -user <id>: Load user record via api.users.get(id) and use its login/secret for request signing.
  • -hdr k=v (repeatable): Adds custom request headers.
  • -cookie k=v (repeatable): Adds custom request cookies.

  Response output controls:

  • -raw: print raw response body (rc.data) and include response headers (rc.resheaders) in output.
  • -json: print parsed response object (rc.obj) as a JSON string.
  • -select a,b.c,...: reduce the parsed response object to only the specified fields/paths.
  • -flatten: flatten the parsed response object into dot-notation keys.

  Signing behavior:

  • When a user is loaded (-user) and has login/secret, a signer hook is provided to lib.fetch:
    • Sets contentType from outgoing content-type header
    • Calls api.signature.create(login, secret, request) and adds the signature header to the request

  Control flow:

  • Runs as a 3-step async series:
    1. Optional user lookup
    2. Optional CSRF bootstrap fetch
    3. Main request fetch + output formatting
  • Terminates via shell.exit on completion or error.

Source:

• shell/shell.js, line 310

Parameters:

(static) stats(options, callback)

Description:

• Shell command: stats

  Queries Elasticsearch-backed metrics via stats.queryElasticsearch and prints results.

  Options parsing:

  • -pool <name>: Elasticsearch pool to use (default: elasticsearch)
  • -groups <list>: Group-by fields (default: tag)
  • -tags <list>: Tag filters
  • -tsize <n>: Terms aggregation size (top N groups)
  • -ssize <n>: Sub-aggregation size
  • -trim <n>: Trim result sets (implementation-specific to stats module)
  • -timedelta <sec>: Bucket size / time step in seconds (converted to ms)
  • -age <sec>: How far back to query (default: 300s, converted to ms)
  • -interval <sec>: Query/rollup interval in seconds (default: 60s, converted to ms)
  • -fields <list>: Metric fields to query (default: host_cpu_util)
  • -count <n>: Limit number of points/rows returned
  • -since <ts>: Start timestamp (epoch seconds)
  • -before <ts>: End timestamp (epoch seconds)
  • -columns <json>: Optional columns configuration (JSON). Parsed with lib.jsonParse

  Output modes:

  • -raw: prints the raw response object as JSON.
  • default: formats each numeric series:
    • rounds each value
    • sorts values descending
    • joins them into a comma-separated string
  • -flatten: flattens nested rc.data using lib.flatten before printing.
  • prints a header line with relative time labels derived from rc.timestamps using lib.toDuration(..., { age: 1, short: 1, round: 2 }).
  • -info: includes rc.info in the formatted output.

  Exits the shell process via shell.exit(err) when done.

Source:

• shell/shell.js, line 412

Parameters: