Pikbase CLI

The binary is gsb. It syncs serverless functions and libraries, manages tenant users, and exposes the same MCP tool catalog the MCP server does.

Commands that touch a tenant prefer explicit CI environment credentials, then .gsb/<tenantCode>/credentials.json, written by gsb init, then legacy MCP configuration. The tenant is chosen by --tenant <code>, else GSB_TENANT_CODE, else the only folder under .gsb/; conflicting selectors fail.

For protected CI jobs, automatic deployment, repeatable seeds, query-selected data packs, and skip/overwrite policy, see CI/CD, deployment, and seeds.

For resource layouts, commits, pull requests, sync metadata, and the distinction between Git state and backend state, see Backend source control with Git.

Setup

gsb init

Signs in to a tenant and stores a token in .gsb/<tenantCode>/credentials.json.

Flag	Description
-t, --tenant <tenantCode>	Tenant code, for example dev1
-e, --email <email>	User email
--password-env <name>	Read the password from an environment variable
--mfa-code-env <name>	Read a six-digit MFA code from an environment variable
--api-url <url>	Override the API base URL
--no-remember	Request a short-lived token instead of a remembered one
-f, --force	Overwrite existing credentials without asking

gsb init --tenant dev1 --email [email protected]

The password is prompted for. If the account requires email MFA, the CLI then securely prompts for the six-digit code and submits the same credentials again. Do not pass passwords or MFA codes directly on the command line — shell history is not a secret store.

For non-interactive use, run the command once with the password variable to issue the challenge. After retrieving the email code through your protected automation, retry with the code in a separate environment variable:

gsb init --tenant dev1 --email [email protected] \
  --password-env GSB_LOGIN_PASSWORD --force --json

gsb init --tenant dev1 --email [email protected] \
  --password-env GSB_LOGIN_PASSWORD --mfa-code-env GSB_MFA_CODE --force --json

The first command fails closed after the challenge is delivered; the retry submits the existing six-digit challenge without rotating it. The CLI never stores the password or MFA code; only the issued session token is saved.

gsb config

Prints the current configuration: tenant, API URL, and where the credentials came from.

Use gsb config --json for automation. Configuration inspection is not authenticated identity verification. Set GSB_TOKEN, GSB_TENANT_CODE, and GSB_BASE_URL in the protected CI environment; never commit the token.

gsb config

gsb settings smtp

Configures the SMTP provider consumed by serverless email functions at _settings.Common.smtp. The command updates GsbModule.settings on the single module named Common and preserves its other settings.

Without workspace SMTP, email delivery uses only Pikbase's original versions of templates included with the workspace. Custom templates and edits to included templates require workspace SMTP. See email delivery.

Flag	Description
--server <host>	SMTP server hostname
--port <number>	SMTP server port
--user-name <name>	SMTP authentication user name
--password-env <name>	Environment variable containing the SMTP password
--email <address>	Default sender email address
--full-name <name>	Optional sender display name
--no-ssl	Disable TLS; TLS is enabled by default
--confirm-tenant <code>	Approve only when the code exactly matches the selected tenant
--json	Print a stable result without SMTP credentials or sender identity

export SMTP_PASSWORD='use-your-secret-store'
gsb --tenant dev1 settings smtp \
  --server smtp.example.com --port 587 \
  --user-name mailer --password-env SMTP_PASSWORD \
  --email [email protected] --full-name 'Example Mailer' \
  --confirm-tenant dev1
unset SMTP_PASSWORD

Do not pass the password as a command-line value or commit it to an environment file. The command does not print or return the password, user name, or sender identity. Port 465 uses implicit TLS; other TLS-enabled ports require STARTTLS, matching the Common SMTP service.

Server cache maintenance

gsb cache clean

Clears the configured tenant's server data, workflow, and function-script caches.

gsb --tenant <tenantCode> cache clean

Routine schema changes, including a new definition or an ordinary column addition, update the affected caches automatically and do not need this command. Run it after large migrations or mass entity-definition updates before validating the schema; this reduces stale-cache and cluster-node synchronization risks. Then verify representative definitions and queries through the normal load-balanced endpoint. If nodes still disagree, repeat the clean or escalate the cluster synchronization issue.

Serverless functions and libraries

gsb pull [name]

Pulls resources from the backend into the working directory. Pulls everything matching the selected types when name is omitted.

Flag	Description
-f, --function	Pull functions
-l, --library	Pull libraries
-d, --doc-template	Pull document templates
-v, --verbose	Verbose output

gsb pull --function
gsb pull "Calculate Order Total" --function --verbose

gsb push <filepath>

Pushes one TypeScript file, or a document template folder, to the backend.

Flag	Description
-t, --type <type>	function, library, or auto (default auto)
-d, --doc-template	Push a document template from a folder
--dry-run	Show what would be pushed without pushing
-v, --verbose	Verbose output

gsb push src/functions/calculate-order-total.ts --dry-run
gsb push src/functions/calculate-order-total.ts --type function

Run --dry-run first. A push overwrites the tenant-side record.

Email delivery: A successful template push saves the workspace copy; it does not activate custom email delivery. Without workspace SMTP, only included templates can be sent, using Pikbase's original versions. Pushed edits do not change those emails, and custom templates cannot be sent. Configure gsb settings smtp to use workspace templates for email. Standalone HTML and PDF generation are not affected. See email delivery.

gsb list

Lists local resources on disk, not tenant records.

Flag	Description
-f, --function	List functions
-l, --library	List libraries
-d, --doc-template	List document templates
-v, --verbose	Verbose output

gsb test <filepath>

Executes a function against the tenant without saving it.

Flag	Description
--entity <entity>	JSON string for the entity context
--params <params>	JSON string for the parameters
-v, --verbose	Verbose output

gsb test src/functions/calculate-order-total.ts \
  --entity '{"id":"order-123"}' \
  --params '{"applyDiscounts":true}'

gsb find [searchTerm]

Searches the tenant for existing serverless functions and libraries — GsbWfFunction and GsbWfCodeLibrary records. It does not search documentation.

Flag	Description
-n, --count <count>	Max results per type (default 25)

gsb find order
gsb find --count 50

Run this before push so you do not create a second function under a name that already exists.

Tools

gsb tools

Lists the MCP tools callable through gsb call, each with its risk classification and whether it needs --yes.

Flag	Description
-r, --read-only	Only list tools classified read
--json	Print a stable result or error envelope

gsb tools --read-only --json

The command reads the local registry and does not require tenant credentials. Structured output preserves each tool's risk and approval metadata.

gsb call <tool>

Calls one MCP tool against the configured tenant. Same implementations as the MCP server; only the transport differs.

Flag	Description
-i, --input <json>	Tool input as a JSON string (default {})
--input-file <path>	Read tool input from a JSON file
-y, --yes	Approve a write, destructive, or side-effecting tool
--json	Stable CLI result/error envelope; inspect operation-specific results as well
--raw	Print raw JSON without the summary header

gsb call query --raw --input '{
  "queryParams": { "entDefName": "Order", "startIndex": 0, "count": 10 }
}'

gsb call save --yes --input-file ./payload.json

Read tools run without --yes. Everything else refuses without it — do not add --yes to a script by default.

gsb mcp [args...]

Runs the MCP server. Unknown options are forwarded. See MCP server.

gsb mcp -y

Users and roles

gsb users add <email>

Creates a user and optionally assigns a role ID.

Flag	Description
--role-id <roleId>	Role ID to assign
--password-env <name>	Read the password from an environment variable
-n, --name <name>	Given name
-s, --surname <surname>	Surname
--write-env <paths...>	Write GSB_TEST_* credentials to one or more ignored env files
--confirm-tenant <code>	Approve only when the code exactly matches the selected tenant
--json	Print a stable result or error envelope

gsb users add [email protected] --role-id <role-id> \
  --write-env .env.test --confirm-tenant <tenantCode> --json

Use --password-env to supply a password. When it is omitted, --write-env is required and the CLI generates the password directly into those files without printing or returning it. Every --write-env target must be git-ignored.

gsb users list

Lists users in the configured tenant.

Flag	Description
-l, --limit <count>	Maximum users to return (default 20)

gsb users roles

Lists the roles available in the configured tenant. Takes no flags.

gsb users assign-role <email> <roleId>

Assigns an existing role ID to an existing user.

Flag	Description
--confirm-tenant <code>	Approve only when the code exactly matches the selected tenant
--json	Print a stable result or error envelope

gsb users reset-password <email>

Resets a user's password.

Flag	Description
--password-env <name>	Read the password from an environment variable
--write-env <paths...>	Write GSB_TEST_* credentials to one or more ignored env files
--confirm-tenant <code>	Approve only when the code exactly matches the selected tenant
--json	Print a stable result or error envelope

The command never prints or returns a password. Without --password-env, an interactive terminal uses a hidden prompt; non-interactive execution requires --write-env and stores a generated password directly in the specified ignored files.

Assistant

gsb assistant seed [manifest]

Creates or updates LlmConfiguration rows from a checked-in manifest. Defaults to .gsb/<tenantCode>/assistant/manifest.json.

Flag	Description
--deployment <name>	Override the LLM deployment name for this tenant
--confirm-tenant <code>	Approve the mutation only when the code exactly matches the selected tenant
--json	Return a stable result or error envelope

gsb --tenant your-tenant assistant seed --deployment your-deployment --confirm-tenant your-tenant --json

Explicit manifests are validated before authentication. If a later configuration fails after earlier writes succeeded, the command returns PARTIAL_APPLICATION with the applied row, failed key, and remaining keys.

Documentation from the terminal

Documentation tools are local, read-only calls that need no tenant.

gsb call getDocs --input '{"methodName":"query"}' --raw
gsb call getApiDocs --raw
gsb call getSchemaDocs --raw
gsb call getServerlessFunctionDocs --raw

Safety

Inspect a tool with gsb tools before invoking it. Write and destructive tools require --yes; do not bypass that in scripts or agent workflows. Keep tokens out of command history and out of committed files.