Grist

What is Grist ?

Grist is a modern relational spreadsheet. It combines the flexibility of a spreadsheet with the robustness of a database.

Grist Features

Grist is a hybrid database/spreadsheet, meaning that:

• Columns work like they do in databases: they are named, and they hold one kind of data.
• Columns can be filled by formula, spreadsheet-style, with automatic updates when referenced cells change.

This difference can confuse people coming directly from Excel or Google Sheets. Give it a chance! There’s also a Grist for Spreadsheet Users article to help get you oriented. If you’re coming from Airtable, you’ll find the model familiar (and there’s also our Grist vs Airtable article for a direct comparison).

Here are some specific feature highlights of Grist:

• Python formulas.
  • Full Python syntax is supported, including the standard library.
  • Many Excel functions also available.
  • An AI Assistant specifically tuned for formula generation (using OpenAI gpt-3.5-turbo or Llama via llama-cpp-python).
• A portable, self-contained format.
  • Based on SQLite, the most widely deployed database engine.
  • Any tool that can read SQLite can read numeric and text data from a Grist file.
  • Enables backups that you can confidently restore in full.
  • Great for moving between different hosts.
• Can be displayed on a static website with grist-static – no special server needed.
• A self-contained desktop app for viewing and editing locally: grist-electron.
• Convenient editing and formatting features.
  • Choices and choice lists, for adding colorful tags to records.
  • References and reference lists, for cross-referencing records in other tables.
  • Attachments, to include media or document files in records.
  • Dates and times, toggles, and special numerics such as currency all have specialized editors and formatting options.
  • Conditional Formatting, letting you control the style of cells with formulas to draw attention to important information.
• Drag-and-drop dashboards.
  • Charts, card views and a calendar widget for visualization.
  • Summary tables for summing and counting across groups.
  • Widget linking streamlines filtering and editing data. Grist has a unique approach to visualization, where you can lay out and link distinct widgets to show together, without cramming mixed material into a table.
  • Filter bar for quick slicing and dicing.
• Incremental imports.
  • Import a CSV of the last three months activity from your bank…
  • …and import new activity a month later without fuss or duplication.
• Integrations.
  • A REST API, Zapier actions/triggers, and support from similar integrators.
  • Import/export to Google drive, Excel format, CSV.
  • Link data with custom widgets, hosted externally.
  • Configurable outgoing webhooks.
• Many templates to get you started, from investment research to organizing treasure hunts.
• Access control options.
  • (You’ll need SSO logins set up to make use of these options; grist-omnibus has a prepackaged solution if configuring this feels daunting)
  • Share individual documents, workspaces, or team sites.
  • Control access to individual rows, columns, and tables.
  • Control access based on cell values and user attributes.
• Self-maintainable.
  • Useful for intranet operation and specific compliance requirements.
• Sandboxing options for untrusted documents.
  • On Linux or with Docker, you can enable gVisor sandboxing at the individual document level.
  • On macOS, you can use native sandboxing.
  • On any OS, including Windows, you can use a wasm-based sandbox.
• Translated to many languages.
• F1 key brings up some quick help. This used to go without saying, but in general Grist has good keyboard support.
• We post progress on 𝕏 or Twitter or whatever and publish monthly newsletters.

If you are curious about where Grist is heading, see our roadmap, drop a question in our forum, or browse our extensive documentation.

Using Grist

If you just want a quick demo of Grist:

• You can try Grist out at the hosted service run by Grist Labs at docs.getgrist.com (no registration needed).
• Or you can see a fully in-browser build of Grist at gristlabs.github.io/grist-static.
• Or you can download Grist as a desktop app from github.com/gristlabs/grist-electron.

To get grist-core running on your computer with Docker, do:

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

Then visit http://localhost:8484 in your browser. You’ll be able to create, edit, import, and export documents. To preserve your work across docker runs, share a directory as /persist:

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

Get templates at templates.getgrist.com for payroll, inventory management, invoicing, D&D encounter tracking, and a lot more, or use any document you’ve created on docs.getgrist.com.

If you need to change the port Grist runs on, set a PORT variable, don’t just change the port mapping:

docker run --env PORT=9999 -p 9999:9999 -v $PWD/persist:/persist -it gristlabs/grist

To enable gVisor sandboxing, set --env GRIST_SANDBOX_FLAVOR=gvisor. This should work with default docker settings, but may not work in all environments.

You can find a lot more about configuring Grist, setting up authentication, and running it on a public server in our Self-Managed Grist handbook.

Building from source

To build Grist from source, follow these steps:

yarn install
yarn run build:prod
yarn run install:python
yarn start
# Grist will be available at http://localhost:8484/

Grist formulas in documents will be run using Python executed directly on your machine. You can configure sandboxing using a GRIST_SANDBOX_FLAVOR environment variable.

• On macOS, export GRIST_SANDBOX_FLAVOR=macSandboxExec uses the native sandbox-exec command for sandboxing.
• On Linux with gVisor’s runsc installed, export GRIST_SANDBOX_FLAVOR=gvisor is an option.
• On any OS including Windows, export GRIST_SANDBOX_FLAVOR=pyodide is available.

These sandboxing methods have been written for our own use at Grist Labs and may need tweaking to work in your own environment - pull requests very welcome here!

Logins

Like git, Grist has features to track document revision history. So for full operation, Grist expects to know who the user modifying a document is. Until it does, it operates in a limited anonymous mode. To get you going, the docker image is configured so that when you click on the “sign in” button Grist will attribute your work to [email protected]. Change this by setting GRIST_DEFAULT_EMAIL:

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

You can change your name in Profile Settings in the User Menu.

For multi-user operation, or if you wish to access Grist across the public internet, you’ll want to connect it to your own Single Sign-On service. There are a lot of ways to do this, including SAML and forward authentication. Grist has been tested with Authentik, Auth0, and Google/Microsoft sign-ins via Dex.

Environment variables

Grist can be configured in many ways. Here are the main environment variables it is sensitive to:

AI Formula Assistant related variables (all optional):

At the time of writing, the AI Assistant is known to function against OpenAI chat completion endpoints for gpt-3.5-turbo and gpt-4. It can also function against the chat completion endpoint provided by llama-cpp-python.

Sandbox related variables:

Forward authentication variables:

Forward authentication supports two modes, distinguished by GRIST_IGNORE_SESSION:

1. With sessions, and forward-auth on login endpoints.

   For example, using traefik reverse proxy with traefik-forward-auth middleware:

   • GRIST_IGNORE_SESSION: do NOT set, or set to a falsy value.
   • Make sure your reverse proxy applies the forward auth middleware to GRIST_FORWARD_AUTH_LOGIN_PATH and GRIST_FORWARD_AUTH_LOGOUT_PATH.
   • If you want to allow anonymous access in some cases, make sure all other paths are free of the forward auth middleware. Grist will trigger it as needed by redirecting to GRIST_FORWARD_AUTH_LOGIN_PATH. Once the user is logged in, Grist will use sessions to identify the user until logout.

2. With no sessions, and forward-auth on all endpoints.

   For example, using HTTP Basic Auth and server configuration that sets the header (specified in GRIST_FORWARD_AUTH_HEADER) to the logged-in user.

• GRIST_IGNORE_SESSION: set to true. Grist sessions will not be used.
• Make sure your reverse proxy sets the header you specified for all requests that may need login information. It is imperative that this header cannot be spoofed by the user, since Grist will trust whatever is in it.

When using forward authentication, you may wish to also set the following variables:

• GRIST_FORCE_LOGIN=true to disable anonymous access.

Plugins:

Grist has a plugin system, used internally. One useful thing you can do with it is include custom widgets in a build of Grist. Custom widgets are usually made available just by setting GRIST_WIDGET_LIST_URL, but that has the downside of being an external dependency, which can be awkward for offline use or for archiving. Plugins offer an alternative.

To “bundle” custom widgets as a plugin:

• Add a subdirectory of plugins, e.g. plugins/my-widgets. Alternatively, you can set the GRIST_USER_ROOT environment variable to any path you want, and then create plugins/my-widgets within that.
• Add a manifest.yml file in that subdirectory that looks like this:

name: My Widgets
components:
  widgets: widgets.json

• The widgets.json file should be in the format produced by the grist-widget repository, and should be placed in the same directory as manifest.yml. Any material in plugins/my-widgets will be served by Grist, and relative URLs can be used in widgets.json.
• Once all files are in place, restart Grist. Your widgets should now be available in the custom widgets dropdown, along with any others from GRIST_WIDGET_LIST_URL.
• If you like, you can add multiple plugin subdirectories, with multiple sets of widgets, and they’ll all be made available.

Google Drive integrations:

Database variables:

Testing: