### Run Grist from Source with Quick Setup Skipped

Source: https://github.com/gristlabs/grist-core/blob/main/README.md

Start Grist from source with the GRIST_IN_SERVICE environment variable set to true to skip the Quick setup page.

```bash
GRIST_IN_SERVICE=true yarn start
```

--------------------------------

### Build Grist Community Edition from Source

Source: https://github.com/gristlabs/grist-core/blob/main/README.md

Steps to install dependencies, build, and start the Grist Community Edition from source code.

```bash
yarn install
yarn install:python
yarn build
yarn start
```

--------------------------------

### Build Grist Full Edition from Source

Source: https://github.com/gristlabs/grist-core/blob/main/README.md

Steps to install dependencies including the EE (Enterprise Edition) components, build, and start the full Grist from source code.

```bash
yarn install
yarn install:ee
yarn install:python
yarn build
yarn start
```

--------------------------------

### Setup Python Virtual Environment

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Prepares the virtual environment with all necessary Python dependencies.

```bash
yarn install:python
```

--------------------------------

### Install Node.js Dependencies

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Installs all project dependencies required for Node.js using Yarn.

```bash
yarn install
```

--------------------------------

### Reference Lookup Examples

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/grist-data-format.md

Examples of using the reference lookup format to set values via the API.

```json
["l", "inv_123"]
```

```json
["l", "inv_123", {"column": "Invoice_ID"}]
```

--------------------------------

### Setup Pyodide Sandbox

Source: https://github.com/gristlabs/grist-core/blob/main/sandbox/pyodide/README.md

Run this command in the sandbox directory to prepare the necessary Python packages for Grist.

```bash
make setup
```

--------------------------------

### Start Grist Server in Development Mode

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Use this command to start the Grist server for development. Reload the browser page after making code changes.

```bash
$ yarn start
```

--------------------------------

### Install Yarn Globally

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Installs Yarn, a JavaScript package manager, globally on your system using npm.

```bash
npm install -g yarn
```

--------------------------------

### Install Dependencies for Grist Core

Source: https://github.com/gristlabs/grist-core/blob/main/README.md

Installs all necessary project dependencies, including Node.js and Python packages.

```bash
yarn install
yarn install:python
```

--------------------------------

### Install Node.js Version via NVM

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Installs the Node.js version specified in the .nvmrc file using Node Version Manager (nvm).

```bash
nvm install
```

--------------------------------

### Create and Use Knockout Observables

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/grainjs.md

Demonstrates how to create, get, set, and peek at values in Knockout observables. Ensure Knockout is imported.

```javascript
import * as ko from 'knockout';

const kObs = ko.observable(17);
kObs();      // Returns 17
kObs(8);
kObs();      // Returns 8
kObs.peek(); // Returns 8
```

--------------------------------

### Specify Model: Qwen QWQ 32B

Source: https://github.com/gristlabs/grist-core/blob/main/README.md

Optionally, specify another AI model. This example uses the Qwen QWQ 32B model, marked as free.

```bash
ASSISTANT_MODEL=qwen/qwq-32b:free
```

--------------------------------

### Install Python Packages

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Installs Python 3.11 and its virtual environment package on Debian-based Linux systems.

```bash
apt install python3.11 python3.11-venv
```

--------------------------------

### Specify Model: Mistral Saba

Source: https://github.com/gristlabs/grist-core/blob/main/README.md

Optionally, specify a different AI model. This example uses Mistral AI's Saba model.

```bash
ASSISTANT_MODEL=mistralai/mistral-saba
```

--------------------------------

### Create and Use GrainJS Observables

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/grainjs.md

Shows how to create, get, and set values in GrainJS observables. Requires importing `Observable` from 'grainjs'.

```javascript
import {Computed, Observable} from 'grainjs';

const gObs = Observable.create(null, 17)
gObs.get();     // Returns 17
gObs.set(8);

gObs.get();     // Returns 8
```

--------------------------------

### Install Specific Chrome Version on Debian-based Systems

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

This command sequence installs a specific Chrome version on Debian-based systems, allowing you to match the CI environment. Ensure CHROME_VERSION is set.

```bash
curl -sS -o /tmp/chrome.deb https://dl.google.com/linux/chrome/deb/pool/main/g/google-chrome-stable/google-chrome-stable_${CHROME_VERSION}_amd64.deb \
  && sudo apt-get install --allow-downgrades -y /tmp/chrome.deb \
  && rm /tmp/chrome.deb \

```

--------------------------------

### Check Node.js Version

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Verify that the installed Node.js version matches the one specified in the .nvmrc file.

```bash
node --version
```

--------------------------------

### Configure Test Database Path

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Specify the path for the test SQLite database file using `TYPEORM_DATABASE`. Example: `TYPEORM_DATABASE=/path/to/test-database.sqlite`.

```bash
TYPEORM_DATABASE=/path/to/test-database.sqlite
```

--------------------------------

### Build DOM with Knockout and koDom

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/grainjs.md

Example of building a DOM element using older Grist functions, with class toggling and text binding using Knockout observables.

```javascript
import * as dom from 'app/client/lib/dom';
import * as kd from 'app/client/lib/koDom';

dom(
  'div',
  kd.toggleClass('active', isActiveObs),
  kd.text(() => vm.nameObs().toUpperCase()),
)
```

--------------------------------

### Define language resource file

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/translations.md

Example of a JSON resource file used for translations, demonstrating key-value mapping, interpolation, and context features.

```json
{
  "AddNewButton": {
    "AddNew": "Add New"
  },
  "DocMenu": {
    "OtherSites": "Other Sites",
    "OtherSitesWelcome": "You are on the {{siteName}} site. You also have access to the following sites:",
    "OtherSitesWelcome_personal": "You are on your personal site. You also have access to the following sites:",
    "AllDocuments": "All Documents",
    "ExamplesAndTemplates": "Examples and Templates",
    "MoreExamplesAndTemplates": "More Examples and Templates"
  },
  "HomeIntro": {
    "Welcome": "Welcome to Grist!",
    "SignUp": "Sign up"
  }
}
```

--------------------------------

### Specify Model: Deepseek R1 Zero

Source: https://github.com/gristlabs/grist-core/blob/main/README.md

Optionally, specify an alternative AI model. This example uses Deepseek's R1 Zero model, marked as free.

```bash
ASSISTANT_MODEL=deepseek/deepseek-r1-zero:free
```

--------------------------------

### Run Tests with Specific Chrome Beta Version

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

After installing Chrome Beta, use these environment variables to run tests against the specified browser and driver versions, pointing to the beta binary.

```bash
SE_BROWSER_VERSION=... \
SE_DRIVER_VERSION=... \
TEST_CHROME_BINARY_PATH="/usr/bin/google-chrome-beta" \
yarn run test:nbrowser
```

--------------------------------

### Add Column Migration in Python

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/migrations.md

Example of adding a migration function to `sandbox/grist/migrations.py` to add a new column to a table. Ensure the `schema_version` is incremented.

```python
from grist.migrations import migration

@migration(schema_version=11)
def migration11(tdset):
  return tdset.apply_doc_actions([
    add_column('_grist_Views_section', 'embedId', 'Text'),
  ])
```

--------------------------------

### Specify Model: Claude 3.7 Sonnet

Source: https://github.com/gristlabs/grist-core/blob/main/README.md

Optionally, specify the AI model to use. This example sets the model to Anthropic's Claude 3.7 Sonnet.

```bash
ASSISTANT_MODEL=anthropic/claude-3.7-sonnet
```

--------------------------------

### Pass Node.js Options to Server

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Pass specific Node.js options to the server being tested using `SERVER_NODE_OPTIONS`. Example: `SERVER_NODE_OPTIONS="--inspect --inspect-brk" GREP_TESTS="Boot" yarn test:nbrowser` to run tests with the debugger.

```bash
SERVER_NODE_OPTIONS="node options" GREP_TESTS="Boot" yarn test:nbrowser
```

--------------------------------

### Debug Grist Server

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Run this command to start the Grist server in debug mode. You can then attach a Node.js debugger client, such as Chrome DevTools.

```bash
$ yarn start:debug
```

--------------------------------

### Listen to Backbone Events with `on`

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/disposal.md

This example demonstrates listening to a Backbone event ('points:scored') using the `on` method. It illustrates a common pattern that can lead to memory leaks if not properly cleaned up, as the callback persists even after the object is destroyed.

```javascript
function Game(basket) {
   basket.on('points:scored', function(team, points) {
      // Update UI to show updated points for the team.
   });
}
```

--------------------------------

### Filter Tests with GREP_TESTS

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Filter which tests to run by providing a pattern to the `GREP_TESTS` environment variable. Example: `GREP_TESTS="Boot" yarn test:nbrowser`.

```bash
GREP_TESTS="pattern" yarn test:nbrowser
```

--------------------------------

### Initial Project Build

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Performs an initial build of the project.

```bash
yarn run build
```

--------------------------------

### Typed Cell Value Examples

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/grist-data-format.md

Examples of various typed cell value structures used in Grist.

```json
["D", 1704945919, "UTC"]
```

```json
["d", 1704844800]
```

```json
["R", "People", 17]
```

```json
["r", "People", [1, 2]]
```

--------------------------------

### Run Client Library Tests

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Execute tests specifically for the client libraries.

```bash
yarn test:client
```

--------------------------------

### Create Knockout Computed Observable

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/grainjs.md

Example of creating a computed observable in Knockout that depends on another observable.

```javascript
ko.computed(() => kObs() * 10);
```

--------------------------------

### Get current epoch timestamp

Source: https://github.com/gristlabs/grist-core/blob/main/app/gen-server/migration/README.md

Retrieve the current date as an epoch timestamp in milliseconds for migration file naming.

```bash
date +%s%N | cut -b1-13
```

--------------------------------

### Use Node.js and Yarn via NVM

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Loads the Node.js and Yarn versions specified by nvm for the current shell session.

```bash
nvm use
```

--------------------------------

### Specify End-to-End Test Log Directory

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Set the directory for end-to-end test logs and screenshots using `MOCHA_WEBDRIVER_LOGDIR`. Example: `MOCHA_WEBDRIVER_LOGDIR=/tmp/grist-tests`.

```bash
MOCHA_WEBDRIVER_LOGDIR=/tmp/grist-tests
```

--------------------------------

### Run Grist with a Custom Boot Key

Source: https://github.com/gristlabs/grist-core/blob/main/README.md

Set a custom boot key when running the Grist Docker image to avoid using the auto-generated one.

```bash
docker run -p 8484:8484 -e GRIST_BOOT_KEY=secret -it gristlabs/grist
```

--------------------------------

### Run Backend Tests

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Execute backend tests. Use `yarn test:server` for tests in `app/server` and `yarn test:gen-server` for tests in `app/gen-server`.

```bash
yarn test:server
```

```bash
yarn test:gen-server
```

--------------------------------

### Client-Side Translation Usage

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/translations.md

Examples of using the 't' function for translating strings in the Grist client UI. It supports basic string translation and interpolation with context.

```typescript
css.otherSitesHeader(
    t('DocMenu.OtherSites'),
    .....
  ),
  dom.maybe((use) => !use(hideOtherSitesObs), () => {
    const personal = Boolean(home.app.currentOrg?.owner);
    const siteName = home.app.currentOrgName;
    return [
      dom('div',
        t('DocMenu.OtherSitesWelcome', { siteName, context: personal ? 'personal' : '' }),
        testId('other-sites-message')

```

```typescript
function makeAnonIntro(homeModel: HomeModel) {
  const signUp = cssLink({href: getLoginOrSignupUrl()}, t('HomeIntro.SignUp'));
  return [
    css.docListHeader(t('HomeIntro.Welcome'), testId('welcome-title')),

```

--------------------------------

### Retry Failing Tests on CI with Systemd (projects)

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

On Linux, use systemd-run to slow down nodejs and browser processes for the projects tests, retrying up to 20 times to mitigate flakiness. Adjust CPUQuota as needed.

```bash
# Example below for projects tests
# You can adapt the value for --cpu-limit
for i in {1..20}; do GREP_TESTS="^yourTestSuiteHere\b" systemd-run --scope -p CPUQuota=50% --user yarn run test:nbrowser:ci -- -- --bail || break; echo "✅ Step $i 🎉"; done
```

--------------------------------

### Navigate to Grist Core Directory

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Change the current directory to the root of the cloned grist-core repository.

```bash
cd grist-core/
```

--------------------------------

### Run Grist with Default Email

Source: https://github.com/gristlabs/grist-core/blob/main/README.md

Configure Grist to run with a single default identity by setting the GRIST_DEFAULT_EMAIL environment variable. This is useful for single-user operation or initial setup.

```bash
docker run --env GRIST_DEFAULT_EMAIL=my@email -p 8484:8484 -v $PWD/persist:/persist -it gristlabs/grist
```

--------------------------------

### Run All Grist Tests

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Execute the full test suite for Grist.

```bash
yarn test
```

--------------------------------

### Enable TypeORM Logging

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Print all SQL commands executed during tests by setting `TYPEORM_LOGGING=true`.

```bash
TYPEORM_LOGGING=true
```

--------------------------------

### Initialize Grist Custom Widget

Source: https://github.com/gristlabs/grist-core/blob/main/static/custom-widget.html

Required methods to register the widget and enable keyboard shortcuts within the Grist environment.

```javascript
grist.ready(); grist.enableKeyboardShortcuts();
```

--------------------------------

### Set Longer Context Model Fallback

Source: https://github.com/gristlabs/grist-core/blob/main/README.md

Optionally, set a model with a larger context window for fallback purposes. This example uses Anthropic's Claude 3 Opus.

```bash
ASSISTANT_LONGER_CONTEXT_MODEL=anthropic/claude-3-opus-20240229
```

--------------------------------

### Server-Side Translation Usage

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/translations.md

Example of using the 't' function on the server side within an Express request object to translate messages for HTTP endpoints. The middleware automatically handles language detection.

```typescript
function getPageTitle(req: express.Request, config: GristLoadConfig): string {
  const maybeDoc = getDocFromConfig(config);
  if (!maybeDoc) {
    return req.t('sendAppPage.Loading') + '...';
  }

  return handlebars.Utils.escapeExpression(maybeDoc.name);
}
```

--------------------------------

### Initialize Mocha Test Runner

Source: https://github.com/gristlabs/grist-core/blob/main/static/test.html

Sets up the Mocha BDD interface and defines global variables to ignore during leak checks.

```javascript
mocha.setup('bdd') onload = function() { $('#app-test').ready(function() { try { window.loadTests(); } catch (err) { console.log("ERROR", err); mocha.failedTests = []; mocha.failedTests.push({title: 'Failed to load', error: err.toString()}); document.getElementById('mocha-status').textContent = 'DONE - FAILED TO LOAD'; return; } mocha.checkLeaks(); // fxdriver_id and ret_nodes are set by selenium, execWebdriverJQuery by webdriverjq.js. mocha.globals(['cmd', 'fxdriver_id', 'ret_nodes', 'execWebdriverJQuery']); var runner = mocha.run(); mocha.failedTests = []; runner.on('fail', function(test, err) { mocha.failedTests.push({title: test.fullTitle(), error: err.toString()}); }); runner.on('end', function() { document.getElementById('mocha-status').textContent = runner.failures > 0 ? 'DONE - FAILURE :(' : 'DONE - SUCCESS :)'; }); }); }; function scrollToBottom() { var bottom = document.getElementById('mocha-end'); bottom.scrollIntoView(true); } afterEach(function() { // keep scrolled to the bottom return scrollToBottom(); }); after(function() { // keep scrolled to the bottom return scrollToBottom(); });
```

--------------------------------

### Run End-to-End Tests in CI Mode

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Execute end-to-end tests in headless mode, suitable for continuous integration environments.

```bash
yarn test:nbrowser:ci
```

--------------------------------

### Generate a new migration

Source: https://github.com/gristlabs/grist-core/blob/main/app/gen-server/migration/README.md

Use the TypeORM CLI to scaffold a new migration file in the current directory.

```bash
npx typeorm migration:create MigrationName
```

--------------------------------

### Specify Chrome Binary Path for Local Testing

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Use this environment variable to point to a specific Chrome binary when running local tests if you encounter version-related failures.

```bash
TEST_CHROME_BINARY_PATH="/usr/bin/google-chrome" yarn run test:nbrowser
```

--------------------------------

### Run End-to-End Tests with Docker

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Execute end-to-end tests within a Docker environment.

```bash
yarn test:docker
```

--------------------------------

### Configure Grist Python Sandboxing with Pyodide

Source: https://github.com/gristlabs/grist-core/blob/main/README.md

Set the GRIST_SANDBOX_FLAVOR environment variable to 'pyodide' for Python formula sandboxing on any OS, including Windows.

```bash
export GRIST_SANDBOX_FLAVOR=pyodide
```

--------------------------------

### Launch Grist container with Docker Compose

Source: https://github.com/gristlabs/grist-core/blob/main/docker-compose-examples/grist-local-testing/README.md

Executes the local Grist instance using the configuration defined in the docker-compose file.

```sh
docker compose up
```

--------------------------------

### Run Common Library Tests

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Execute tests for the common libraries shared between the client and server.

```bash
yarn test:common
```

--------------------------------

### Enable Verbose Logging

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

View detailed logs when a server is spawned by setting `VERBOSE=1`. Useful for debugging end-to-end and backend tests.

```bash
VERBOSE=1
```

--------------------------------

### Enable Debug Output

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Keep the server running after tests complete and provide more detailed output by setting `DEBUG=1`.

```bash
DEBUG=1
```

--------------------------------

### Run Grist with Data Persistence

Source: https://github.com/gristlabs/grist-core/blob/main/README.md

Runs Grist and mounts a local 'persist' directory to preserve data across container restarts.

```sh
docker run -p 8484:8484 -v $PWD/persist:/persist -it gristlabs/grist
```

--------------------------------

### Generate Home Database Schema with SchemaCrawler

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/database.md

This command uses SchemaCrawler to generate an SVG graph of the Home database schema. It connects to a SQLite database, specifies standard info level, uses portable names, and filters tables to exclude billing and migration-related ones. Adapt the database path and grep-tables option as needed.

```bash
# You may adapt the --database argument to fit with the actual file name
# You may also remove the `--grep-tables` option and all that follows to get the full schema.
# database path needs to be absolute in some schemacrawler implementations
$ schemacrawler --server=sqlite --database=$(pwd)/landing.db --info-level=standard \
  --portable=names --command=schema --output-format=svg \
  --output-file=/tmp/graph.svg \
  --grep-tables="products|billing_accounts|limits|billing_account_managers|activations|migrations" \
  --invert-match
```

--------------------------------

### Set OpenRouter API Key

Source: https://github.com/gristlabs/grist-core/blob/main/README.md

Configure the environment variable with your OpenRouter API key. This is required to authenticate with OpenRouter. Sign up at https://openrouter.ai/.

```bash
ASSISTANT_API_KEY=your_openrouter_api_key_here
```

--------------------------------

### Run Data Engine Tests

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Execute tests for the Grist data engine.

```bash
yarn test:python
```

--------------------------------

### Base CSS Styles for Custom Widgets

Source: https://github.com/gristlabs/grist-core/blob/main/static/custom-widget.html

Standard CSS reset and theme-aware styling for consistent widget appearance.

```css
body { margin: 0; font-size: 13px; color: var(--grist-theme-text, #262633); font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol; } .title { font-size: 20px; font-weight: 600; } .title-light { font-size: 16px; font-weight: 400; color: var(--grist-theme-text-light, #929299); } a { color: var(--grist-theme-link, #16B378); text-decoration: none; } a:hover, a:focus { text-decoration: underline; }
```

--------------------------------

### Run Smoke Tests

Source: https://github.com/gristlabs/grist-core/blob/main/documentation/develop.md

Execute a minimal test to verify Grist can open, create, and edit a document.

```bash
yarn test:smoke
```

--------------------------------

### Set OpenRouter API Endpoint

Source: https://github.com/gristlabs/grist-core/blob/main/README.md

Configure the environment variable to point to OpenRouter's API for chat completions. This is a required step for OpenRouter integration.

```bash
ASSISTANT_CHAT_COMPLETION_ENDPOINT=https://openrouter.ai/api/v1/chat/completions
```

--------------------------------

### Configure Grist Python Sandboxing with gVisor

Source: https://github.com/gristlabs/grist-core/blob/main/README.md

Set the GRIST_SANDBOX_FLAVOR environment variable to 'gvisor' to use gVisor's runsc for Python formula sandboxing on Linux.

```bash
export GRIST_SANDBOX_FLAVOR=gvisor
```

--------------------------------

### Run Default Grist Container

Source: https://github.com/gristlabs/grist-core/blob/main/README.md

Pulls the latest Grist image and runs it on port 8484. Visit http://localhost:8484 in your browser.

```sh
docker pull gristlabs/grist
docker run -p 8484:8484 -it gristlabs/grist
```