Start with the CLI

Task

Run a local VoLCA server, then use the CLI to retrieve the inventory of Swiss Electricity mix, reference 1 kWh. The CLI connects to a running engine; this is not a serverless command.

Prerequisites

• A Linux or macOS terminal, curl, and internet access for the downloads below.
• A supported VoLCA v0.12.0 release. Windows users can use the release’s PowerShell installer and adapt shell commands.
• A fresh working directory and an available local port. No VoLCA account is needed.

Action

1. Install the released engine

Download and inspect the installer before executing it:

curl -fL https://raw.githubusercontent.com/ccomb/volca/v0.12.0/install.sh -o install.sh
# Read install.sh before running it.
sh install.sh v0.12.0
export PATH="$HOME/.local/bin:$PATH"
volca --version

The installer verifies the binary and reference-data release checksums. Alternatively, after reviewing the installer, the one-command form is:

curl -fsSL https://raw.githubusercontent.com/ccomb/volca/v0.12.0/install.sh | sh -s -- v0.12.0

2. Prepare a public database

Use a new directory so these downloads do not replace your existing configuration:

mkdir volca-cli-demo
cd volca-cli-demo
curl -fL https://app.volca.run/preloaded/bafu-2026-v1.zip -o bafu-2026-v1.zip
curl -fL https://www.volca.run/onboarding/volca.toml -o volca.toml

Inspect volca.toml. It binds the server to 127.0.0.1:18765 and loads bafu-2026-v1.zip as bafu-2026-v1. Keep both files in this directory. This is a 37,703,538-byte public database archive; no LCIA method download is required.

Verify the archive before starting the engine:

sha256sum bafu-2026-v1.zip

On macOS, use shasum -a 256 bafu-2026-v1.zip. Continue only if the output is exactly:

5b5742de3bfe31a4cbeca6fe07e29c814e84c3fa5fec4d29fbb771042812664c  bafu-2026-v1.zip

3. Start the server in terminal 1

From the directory containing volca.toml:

volca --config volca.toml server --port 18765

Leave this terminal running. Wait for database loading and server startup to finish.

4. Query from terminal 2

Open a second terminal in the same volca-cli-demo directory. Search for candidate activities:

volca --config volca.toml --url http://127.0.0.1:18765 --db bafu-2026-v1 activities --name "Electricity mix" --geo CH

Search is fuzzy and can return many candidates. Do not select the first row. For this pinned BAFU archive, use the independently checked exact Swiss Electricity mix process:

volca --config volca.toml --url http://127.0.0.1:18765 --db bafu-2026-v1 --format json inventory 3dd9f4d2-ebc3-32d6-8138-ba4253c4ebc3_a99c8f9b-0339-5c79-a622-08e1b5bee775 > inventory.json

Keep --config volca.toml even when supplying --url; the v0.12.0 CLI requires the configuration for this exercise. Open inventory.json in a text editor. Stop your server with Ctrl+C in terminal 1 when finished.

Expected result

inventory.json contains cumulative emissions and resources for 1 kWh. Its metadata reports totalFlows: 2147, emissionFlows: 1795, and resourceFlows: 352. The local CLI and HTTP API returned identical inventory JSON for this released pair.

These flow counts are not an environmental score. Keep each quantity with its unit and compartment. Do not sum across units or rank environmental importance from raw quantities.

Troubleshooting

• Cannot connect: start the server in terminal 1 and wait for readiness. A config file alone does not start the server for the CLI query.
• Port already in use: do not reuse an unknown process. Stop your own earlier server or choose a free port, then change both the server command/configuration and every client URL consistently.
• Missing command: add the installer’s binary directory to your PATH, or use its full path.
• Missing database or config: run both terminals from the directory containing the checked archive and volca.toml.
• Different checksum: stop. Remove only the downloaded exercise archive and download it again before using these expected results.

Next step

Use the same server for your first HTTP API request, or explore the CLI reference and REPL. For a deployed service rather than a local exercise, see the self-hosted quick start.