CLI Reference

The Marmot CLI lets you interact with your data catalog directly from the terminal.

Looking for Ingestion?

The CLI also supports populating your catalog from data sources via the ingest command.

View Ingestion Docs

Installation

AutomaticManual

Homebrew

brew install marmot

Install script

curl -fsSL get.marmotdata.io | sh

Verify Scripts

It's good practice to inspect the contents of any script before piping it into bash.

1

Download the binary

Download the latest Marmot binary for your platform from GitHub Releases.

2

Make it executable

chmod +x marmot

3

Move to your PATH

sudo mv marmot /usr/local/bin/

---

Authentication

Sign in once with marmot login. It opens your browser, you sign in the way you always do, and the CLI keeps a token for you.

marmot login https://marmot.example.com

That is all most people need. Every other command uses the token from then on. It lasts 24 hours; run marmot login again when it has expired.

Useful options

# Skip the browser and print the sign-in link instead.
# Open it anywhere, then paste the address the browser ends up on back here.
marmot login https://marmot.example.com --no-launch-browser

# Sign in again even if you still have a valid token
marmot login https://marmot.example.com --force

# Print the token, for scripts
marmot login https://marmot.example.com --print-token

# Forget the token
marmot logout

What happens behind the scenes

The CLI opens the Marmot sign-in page in your browser and waits on a local port for the browser to come back with a code. It swaps that code for a token and saves it in ~/.config/marmot/credentials.json. The token is a signed JWT with your user id, your roles and their permissions, and an expiry. This is plain OAuth 2.0 with PKCE. There is no client secret and nothing to configure.

Pushing to a registry on your Marmot host

Login also makes the token available to docker, crane and oras for the Marmot host, so those tools can push to a registry served there without a docker login.

This needs docker-credential-marmot on your PATH. It is just the marmot binary under another name, and the install script sets it up. If you installed marmot some other way:

ln -s "$(command -v marmot)" "$(dirname "$(command -v marmot)")/docker-credential-marmot"

Without it, login writes the token straight into ~/.docker/config.json. That works until the token expires, and not at all if Docker Desktop manages your credentials. Login tells you when that is the case.

API Keys

API keys can still be used and always take priority over cached login tokens.

# Via flag
marmot assets list --api-key mrmot_abc123

# Via environment variable
export MARMOT_API_KEY=mrmot_abc123

Auth Priority

When multiple credentials are available, the CLI uses the first one found:

1. --api-key flag or MARMOT_API_KEY environment variable
2. Cached OAuth token from marmot login (for the active context)
3. Kubernetes service account token (auto-detected in-cluster)

---

Contexts

Contexts let you work with multiple Marmot instances (e.g. staging and production). A context is created automatically when you run marmot login.

# Login creates a context named after the hostname
marmot login https://marmot.example.com
# → Context "marmot.example.com" created and activated.

marmot login https://staging.marmot.dev
# → Context "staging.marmot.dev" created and activated.

# List all contexts (* = active)
marmot context list
#   marmot.example.com   https://marmot.example.com   (token valid)
# * staging.marmot.dev   https://staging.marmot.dev    (token valid)

# Switch active context
marmot context use marmot.example.com

# Remove a context and its cached token
marmot context delete staging.marmot.dev

---

Configuration

You can also configure the CLI with flags, environment variables or a config file. These are checked in order of precedence.

CLI Flags

marmot assets list --host https://marmot.example.com --api-key my-key

Environment Variables

export MARMOT_HOST=https://marmot.example.com
export MARMOT_API_KEY=my-key

Config File

marmot config init

This creates ~/.config/marmot/config.yaml interactively. You can also use marmot config set <key> <value> to set individual values.

Key	Description	Default
host	Marmot server URL	http://localhost:8080
api_key	API key for authentication	(none)
output	Default output format (table, json, yaml)	table
current_context	Active context name	(none)

---

Output Formats

All commands support --output / -o with table (default), json or yaml.

marmot assets list -o json | jq '.assets[].name'

---

Commands

All list commands support --limit and --offset for pagination. Destructive commands prompt for confirmation unless --yes is passed. Run marmot <command> --help for full flag details.

marmot login

marmot login [url] [flags]

Authenticate with a Marmot instance via browser using OAuth 2.0 PKCE. A valid cached token is reused. If no URL is provided and no context is active, prompts for one. Creates a context automatically and registers the token with the Docker credential store for the instance's host.

Flag	Description
--force	Sign in again even if a valid token is cached
--print-token	Print the access token on stdout; status messages go to stderr
--no-launch-browser	Print the sign-in URL instead of opening a browser; the callback URL can be pasted on stdin

marmot logout

marmot logout

Remove the cached authentication token for the active context, and the registry credential login registered for its host.

marmot context

marmot context <list | use | delete>

Manage named contexts for switching between Marmot instances. Contexts are created automatically by marmot login.

Subcommand	Description
list	Show all contexts with token status
use <name>	Switch active context
delete <name>	Remove context and its cached token

marmot assets

marmot assets <list | get | search | delete | summary | tags | owners> [flags]

Browse, search and manage assets in your catalog. Use list and search with --types, --providers and --tags to filter results. tags add and tags remove take an asset ID and a tag.

marmot search

marmot search <query> [flags]

Unified search across assets, glossary terms, teams and users. Filter by result type with --types.

marmot glossary

marmot glossary <list | get | search | create | update | delete> [flags]

Manage glossary terms. Create terms with --name and --definition, optionally nesting them under a parent with --parent-id.

marmot runs

marmot runs <list | get | entities> [flags]

View pipeline ingestion runs. Filter with --pipelines and --statuses.

marmot lineage

marmot lineage get <asset-id> [flags]

View the upstream and downstream lineage graph for an asset. Control traversal depth with --depth.

marmot users

marmot users <me | list | get> [flags]

View user information. me shows the currently authenticated user.

marmot apikeys

marmot apikeys <list | create | delete> [flags]

Manage API keys for authentication. The full key is only shown once at creation time.

marmot teams

marmot teams <list | get | members> [flags]

View teams and their members.

marmot metrics

marmot metrics <summary | by-type | by-provider | top-assets | top-queries> [flags]

View catalog metrics and usage statistics. top-assets and top-queries require a time range via --start and --end (RFC3339 format, defaults to the last 30 days).

marmot admin

marmot admin <reindex | reindex-status>

Administrative operations. reindex triggers a full search reindex and reindex-status checks its progress.

marmot service-accounts

marmot service-accounts <list | get | create | delete> [flags]
marmot service-accounts apikeys <list | create | delete> [flags]

Manage service accounts and their API keys. A service account is a principal with no person behind it: CI, an ingestion job, an agent. Create one with --name and an optional --roles list of role IDs, then issue it a key. An account holds up to five keys and the key itself is printed once, at creation.

marmot service-accounts create --name catalog-copilot \
  --description "Answers questions in #data-help. Owned by the platform team."

marmot service-accounts apikeys create \
  --service-account <id> --name production --expires-in-days 90

Flag	On	Description
--name	create	Account or key name. Required.
--description	create	What the account is for and who owns it.
--roles	create	Comma-separated role IDs to assign.
--service-account	apikeys *	The account to act on. Required.
--expires-in-days	apikeys create	Key expiry. 0 never expires.

See users, roles and access for what to grant.

marmot ingest

marmot ingest --config <file> [flags]

Run plugins on this machine and push what they find to Marmot, rather than having the server run them. Use it in CI, or when the source is not reachable from the Marmot server. The configuration file lists the plugins to run and their settings; see populating with the CLI.

Flag	Description
--config, -c	Path to the ingestion config file. Required.
--quiet, -q	Hide info logs and show errors only. On by default.
--destroy, -d	Delete every asset this pipeline created. Prompts for confirmation.

marmot generate-encryption-key

marmot generate-encryption-key

Print a new 32-byte key for server.encryption_key, which Marmot uses to encrypt pipeline credentials at rest. Losing the key means losing the credentials encrypted with it, so store it wherever you keep your other secrets before starting the server.

marmot credential-helper

marmot credential-helper <get | store | erase | list>

The Docker credential helper protocol, so docker, crane and oras can push to a registry served by your Marmot host using your marmot login session. You do not call this yourself: Docker does, through the docker-credential-marmot symlink the install script creates. See authentication above.

marmot run

marmot run [--config <file>]

Start a Marmot server from the same binary as the CLI. This is what the container image runs. See deployment for running it in production.

marmot config

marmot config <init | set | get | list>

Manage CLI configuration. See Configuration above for details.

---

Tab Completion

Generate shell completions with marmot completion <shell>. Supported shells are bash, zsh, fish and powershell.

source <(marmot completion bash)

---

Next Steps

Populating Your Catalog

Learn about all the ways to add assets to Marmot

Query Language

Use advanced search queries to find assets

REST API

View the full API documentation for custom integrations

Deployment Options

Deploy Marmot to production with Docker, Helm or the CLI

Need Help?

Join the Discord community to ask questions and connect with other Marmot users.

Join Discord