Configuration Reference

The refget CLI uses a TOML configuration file and environment variables to manage settings. This page documents all configuration options.

Configuration priority

Settings are resolved in this order (highest priority first):

1. CLI flags - Command-line arguments
2. Environment variables - System environment
3. Config file - ~/.refget/config.toml
4. Defaults - Built-in default values

Config file location

By default, the configuration file is located at:

~/.refget/config.toml

Override this with the REFGET_CONFIG environment variable:

export REFGET_CONFIG=/path/to/custom/config.toml

View the current config path:

refget config path

Config file format

The configuration file uses TOML format with these sections:

Complete example

# Local RefgetStore path
[store]
path = "~/.refget/store"

# Seqcol API servers for remote queries
[[seqcol_servers]]
url = "https://seqcolapi.databio.org"
name = "databio"

[[seqcol_servers]]
url = "https://my-internal-server.org"
name = "internal"

# Remote RefgetStores for sequence retrieval
[[remote_stores]]
url = "s3://my-bucket/refget-store/"
name = "s3-store"

# Sequence servers (GA4GH refget sequences API)
[[sequence_servers]]
url = "https://www.ebi.ac.uk/ena/cram"
name = "ena"

# Database settings for admin commands
[admin]
postgres_host = "localhost"
postgres_port = "5432"
postgres_db = "refget"
postgres_user = "postgres"
postgres_password = "secret"

Configuration sections

store

Local RefgetStore settings.

Key	Type	Default	Description
path	string	~/.refget/store	Path to local RefgetStore directory

[store]
path = "~/.refget/store"

seqcol_servers

List of sequence collection API servers. Used by refget seqcol commands.

Key	Type	Required	Description
url	string	Yes	Server URL (e.g., https://seqcolapi.databio.org)
name	string	No	Friendly name for the server

[[seqcol_servers]]
url = "https://seqcolapi.databio.org"
name = "databio"

Default: [{url: "https://seqcolapi.databio.org", name: "databio"}]

remote_stores

List of remote RefgetStores for sequence retrieval. Used by refget store commands when accessing remote data.

Key	Type	Required	Description
url	string	Yes	Store URL (supports s3://, https://, local paths)
name	string	No	Friendly name for the store

[[remote_stores]]
url = "s3://my-bucket/refget-store/"
name = "cloud-store"

Default: [] (empty list)

sequence_servers

List of GA4GH refget sequence servers. Used by SequenceClient for raw sequence retrieval.

Key	Type	Required	Description
url	string	Yes	Server URL
name	string	No	Friendly name

[[sequence_servers]]
url = "https://www.ebi.ac.uk/ena/cram"
name = "ena"

Default: [] (empty list)

admin

Database connection settings for admin commands (refget admin).

Key	Type	Default	Description
postgres_host	string	localhost	PostgreSQL server hostname
postgres_port	string	5432	PostgreSQL server port
postgres_db	string	refget	Database name
postgres_user	string	postgres	Database username
postgres_password	string	(none)	Database password

[admin]
postgres_host = "localhost"
postgres_port = "5432"
postgres_db = "refget"
postgres_user = "postgres"
postgres_password = "secret"

Environment variables

Environment variables override config file values. Use these for deployment or CI/CD.

General settings

Variable	Config equivalent	Description
REFGET_CONFIG	(file path)	Path to config file
REFGET_STORE	store.path	Local store path
REFGET_STORE_PATH	store.path	Local store path (explicit form)

Server overrides

These replace the entire server list with a single server:

Variable	Config equivalent	Description
REFGET_SEQCOL_URL	seqcol_servers	Single seqcol server URL
REFGET_STORE_URL	remote_stores	Single remote store URL
REFGET_SEQUENCE_URL	sequence_servers	Single sequence server URL

Database settings

Variable	Config equivalent	Description
POSTGRES_HOST	admin.postgres_host	Database host
POSTGRES_PORT	admin.postgres_port	Database port
POSTGRES_DB	admin.postgres_db	Database name
POSTGRES_USER	admin.postgres_user	Database user
POSTGRES_PASSWORD	admin.postgres_password	Database password

Example: Docker deployment

docker run -e POSTGRES_HOST=db \
           -e POSTGRES_DB=refget \
           -e POSTGRES_USER=app \
           -e POSTGRES_PASSWORD=secret \
           -e REFGET_SEQCOL_URL=https://seqcolapi.databio.org \
           my-refget-app

CLI config commands

Manage configuration from the command line:

# Initialize config interactively
refget config init

# Show all configuration
refget config show

# Show specific section
refget config show store
refget config show admin

# Get a specific value
refget config get store.path
refget config get admin.postgres_host

# Set a value
refget config set store.path ~/my-store
refget config set admin.postgres_host db.example.com

# Add a server
refget config add seqcol_server https://my-server.org
refget config add remote_store s3://my-bucket/store/

# Remove a server
refget config remove seqcol_server databio
refget config remove remote_store my-store

# Show config file path
refget config path

# Validate config file
refget config validate

Common configurations

Minimal config (local only)

[store]
path = "~/.refget/store"

Research server

[store]
path = "/data/refget/store"

[[seqcol_servers]]
url = "https://seqcolapi.databio.org"
name = "databio"

[[remote_stores]]
url = "s3://lab-bucket/refget-store/"
name = "lab-store"

Admin/server deployment

[admin]
postgres_host = "db.internal"
postgres_port = "5432"
postgres_db = "seqcol_prod"
postgres_user = "seqcol_app"
# Password via POSTGRES_PASSWORD env var for security

Troubleshooting

Config not being read

1. Check the config path: refget config path
2. Verify file exists and is valid TOML: refget config validate
3. Check environment overrides: env | grep REFGET

Server connection issues

1. Verify server URLs are correct: refget config show seqcol_servers
2. Test connectivity: refget seqcol info
3. Check for environment overrides: echo $REFGET_SEQCOL_URL

Database connection issues

1. Verify settings: refget config show admin
2. Test connection: refget admin status
3. Check environment variables are set correctly