README
¶
DataTug CLI & agent for web UI
 |
DataTug is an open-source, CLI-first data exploration platform with a Web UI, designed to help you explore, query, and connect data across multiple sources without losing context. It automatically surfaces related data — even across different systems — so you can move naturally between datasets, queries, and results. Free for personal use, DataTug keeps your workflows transparent, versioned, and portable, whether you work locally, in GitHub, or in the cloud. |
Our approach to development
We build with our own tooling:
- SpecScore — specify requirements as
SpecScore.mdartifacts - SpecStudio — author & manage specs across their lifecycle
- inGitDB — store structured data in Git where applicable
- DALgo — data access layer for Go
- cover100.dev — drive toward 100% test coverage
- DataTug — query & explore data
♺ Continuous Integration — 
Help wanted to get test coverage to 100%.
Installation
macOS / Linux — curl
(p=$(mktemp) && trap 'rm -f "$p"' EXIT && curl -fsSL https://datatug.io/install/get-cli -o "$p" && sh "$p")
Environment overrides: DATATUG_VERSION (default: latest release), DATATUG_INSTALL_DIR (default: ~/.local/bin).
Windows — PowerShell
$p=Join-Path $env:TEMP ("datatug-"+[guid]::NewGuid()+".ps1"); try { irm https://datatug.io/install/get-cli.ps1 -OutFile $p -EA Stop; & $p } finally { Remove-Item $p -EA SilentlyContinue }
Environment overrides: DATATUG_VERSION, DATATUG_INSTALL_DIR (default: %LOCALAPPDATA%\DataTug\bin). Current Windows releases support amd64.
macOS / Linux — Homebrew (tap)
brew install --cask datatug/tap/datatug
The direct installers and Homebrew package do not require Go. See the full installation guide or the official AI-agent instructions.
Updating
datatug self-update
datatug self-update --check # report whether a newer release exists, without applying it
Homebrew installs run brew update && brew upgrade --yes --cask -- datatug; direct installs from curl or PowerShell download and checksum-verify the latest release and swap the binary in place. See spec/features/cli/self-update.
Installing and upgrading related CLIs
datatug install # list ingitdb, ovdb and specscore, with install status
datatug install ovdb # show details and install it the same way datatug itself was installed
datatug install ovdb --dry-run # report the planned action without downloading or writing anything
datatug upgrade # report current/latest/verdict for every installed fleet CLI plus datatug itself
datatug upgrade --all # upgrade every installed fleet CLI plus datatug itself, after one confirmation
ingitdb validates and edits the inGitDB databases DataTug reads; ovdb
runs a user-owned OpenVaultDB server DataTug can query as a catalog;
specscore lints DataTug's own specifications. datatug upgrade is the
fleet-wide counterpart to self-update: datatug self-update is exactly
datatug upgrade datatug, built from the same catalog configuration, so
the two never disagree. See
spec/features/cli/install.
What you can do with DataTug
- Explore data everywhere — SQL databases, cloud data sources, logs, and APIs (HTTP / REST)
- CLI-first workflows with a Web UI — dashboards, charts, and shared views
- Create parametrised queries and query sets for repeatable troubleshooting and investigation scenarios
- Automatically navigate related data across tables, views, APIs, and different data sources
- Build data pipelines to transform, combine, and enrich data
- Document schemas and metadata with a built-in wiki
- Version everything with Git — queries, dashboards, pipelines, and settings stored as readable project files
- Choose where your project lives:
- Local directory (fully offline)
- GitHub repository
- DataTug Cloud
DataTug turns scattered data into a connected, navigable workspace — combining the speed of the CLI with the clarity of a Web UI for exploration, troubleshooting, and collaboration.
What it is and why?
This is an agent service for https://datatug.app that you can run on your local machine, or some server to allow DataTug app to scan databases & execute SQL requests.
It can be run with your user account credentials (e.g. trusted connection) or under some service account.
Would you steal my data?
No, we won't.
The project is free and open source codes available at https://github.com/datatug/datatug. You are welcome to check - we do not look into your data.
Where are metadata stored?
When DataTug agent scans or compare your database it stores meta information in a datatug project as set of simple to understand & easy to compare JSON files.
We recommend to check-in the project to some source versioning control system like GIT.
You can run commands for different projects by passing path to DataTugProject folder. E.g.:
> datatug show --project ~/my-datatug-projects/DemoProject
Paths to the DataTug project files, and their names are stored in ~/datatug.yaml in the root of your user's home
directory.
This allows you to address a DataTug project in a console using a short alias. Like this:
> datatug show -p DemoProject
If the current directory is a DataTug project folder you don't need to specify project name or path.
> datatug show
How to get the DataTug CLI?
Use one of the supported methods in Installation. None requires Go.
Then verify the installed CLI:
> datatug --help
How to run?
Check the CLI section on how to run DataTug agent.
Supported databases
At the moment we any DB supported by DALgo. Like:
Supported sql Databases:
Datatug can work with sql DBs if a relevant driver has been linked into datatug
- SQLite - via github.com/mattn/go-sqlite3
- Microsoft SQL Server - via go-mssqldb
We are open for pull requests to support other sql DBs.
For developers
Read README-dev.md for details on how to setup, debug, and contribute.
Sample Databases
By Database Platform
- SQLite
- MS SQL Server
- Oracle
Northwind Database
Open Source Libraries we use
- tview - Terminal UI library with rich, interactive widgets — written in Golang
- DALgo - Database Abstraction Layer for Go
- https://gihub.com/strongo/validation - helpers for requests & models validations
Contributing
We welcome contributions to DataTug! Please read our contributing guidelines for more information on how to contribute to the project.
Download
License
Apache License
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
pkg
|
|
|
accesspolicies
Package accesspolicies discovers and decodes the DALgo access policies a DataTug user keeps on disk, runs a query through them as a secured application would, and explains what the policies did to that query.
|
Package accesspolicies discovers and decodes the DALgo access policies a DataTug user keeps on disk, runs a query through them as a secured application would, and explains what the policies did to that query. |
|
auth/device
Package device provides DataTug's shared auth.sneat.co device-login command.
|
Package device provides DataTug's shared auth.sneat.co device-login command. |
|
chat
Package chat implements the narrow DataTug Chat proof of concept: an ADK agent may invoke one DTQL tool, and DataTug executes that tool into a structured secureread.Result.
|
Package chat implements the narrow DataTug Chat proof of concept: an ADK agent may invoke one DTQL tool, and DataTug executes that tool into a structured secureread.Result. |
|
dbcopy
Package dbcopy implements the `datatug db copy` cross-engine database copy primitive.
|
Package dbcopy implements the `datatug db copy` cross-engine database copy primitive. |
|
dbcopy/filter
Package filter — CLI mini-syntax parsers.
|
Package filter — CLI mini-syntax parsers. |
|
dtentity
Package dtentity provides JSON encode/decode for *datatug.Entity that correctly round-trips Tables (the "generated mapping copy") - see TableKeyDoc for why the model's own JSON tags can't do this in datatug-core v0.17.0.
|
Package dtentity provides JSON encode/decode for *datatug.Entity that correctly round-trips Tables (the "generated mapping copy") - see TableKeyDoc for why the model's own JSON tags can't do this in datatug-core v0.17.0. |
|
dtroot
Package dtroot resolves the CLI-local data directory (~/datatug), used for CLI-only state and the "clone GitHub projects under here" convention.
|
Package dtroot resolves the CLI-local data directory (~/datatug), used for CLI-only state and the "clone GitHub projects under here" convention. |
|
executionstore
Package executionstore composes immutable repository-backed execution receipts with server-private SQLite snapshot bytes and lifecycle state.
|
Package executionstore composes immutable repository-backed execution receipts with server-private SQLite snapshot bytes and lifecycle state. |
|
httpsource
Package httpsource translates a datatug project's HTTP-type QueryDefs into a dalgo2http-backed dal.DB: one dalgo2http.Collection per query (see BuildCollection for the translation and its sensible-default policy for RowsPath/KeyField, since the QueryDef JSON schema does not yet carry those explicitly), snapshot fallback wired to the project's fixtures/http/ directory (see fixtureFS for how its flatly-named fixture files are bridged to dalgo2http's per-request snapshot keying), live-then-snapshot mode.
|
Package httpsource translates a datatug project's HTTP-type QueryDefs into a dalgo2http-backed dal.DB: one dalgo2http.Collection per query (see BuildCollection for the translation and its sensible-default policy for RowsPath/KeyField, since the QueryDef JSON schema does not yet carry those explicitly), snapshot fallback wired to the project's fixtures/http/ directory (see fixtureFS for how its flatly-named fixture files are bridged to dalgo2http's per-request snapshot keying), live-then-snapshot mode. |
|
incidentstore
Package incidentstore persists the Incidentius event stream in a repository.
|
Package incidentstore persists the Incidentius event stream in a repository. |
|
personalqueries
Package personalqueries resolves the on-disk directory a principal's personal (never-shared) queries live under for `datatug serve` — see ResolveProjectDir.
|
Package personalqueries resolves the on-disk directory a principal's personal (never-shared) queries live under for `datatug serve` — see ResolveProjectDir. |
|
querywrite
Package querywrite holds the guards every saved-query write path of this agent shares - the legacy queries/create_query, update_query and delete_query routes and queries/capture - so each check has one definition, whichever route a write takes.
|
Package querywrite holds the guards every saved-query write path of this agent shares - the legacy queries/create_query, update_query and delete_query routes and queries/capture - so each check has one definition, whichever route a write takes. |
|
secureread
Package secureread is the policy-enforced read executor for the DataTug agent server (`datatug serve`).
|
Package secureread is the policy-enforced read executor for the DataTug agent server (`datatug serve`). |
|
sneatv
Package sneatv keeps the small compatibility surface used by datatug-cli while filetug's UI helpers live in dedicated packages.
|
Package sneatv keeps the small compatibility surface used by datatug-cli while filetug's UI helpers live in dedicated packages. |