Version: Preview

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.

Installation

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.

Authentication

The recommended way to authenticate is with marmot login, which opens a browser to sign in using your organisation's identity provider (Google, Okta, Keycloak, etc.) via OAuth 2.0 PKCE. API keys are still fully supported.

# First time — prompts for your Marmot URL, opens browser
marmot login

# Or pass the URL directly
marmot login https://marmot.example.com

The token is cached locally at ~/.config/marmot/credentials.json and used automatically by all subsequent commands. Tokens expire after 24 hours — just run marmot login again to re-authenticate.

# Remove cached token
marmot logout

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:

--api-key flag or MARMOT_API_KEY environment variable
Cached OAuth token from marmot login (for the active context)
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 [url] [flags]

Authenticate with a Marmot instance via browser using OAuth 2.0 PKCE. If no URL is provided and no context is active, prompts for one. Creates a context automatically.

Flag	Description
`--force`	Re-authenticate even if a valid token exists

marmot logout

marmot logout

Remove the cached authentication token for the active context.

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.

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 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

CLI Reference

Looking for Ingestion?

Installation

Homebrew

Install script

Download the binary

Make it executable

Move to your PATH

Authentication

API Keys

Auth Priority

Contexts

Configuration

CLI Flags

Environment Variables

Config File

Output Formats

Commands

marmot logout

marmot context

marmot assets

marmot search

marmot glossary

marmot runs

marmot lineage

marmot users

marmot apikeys

marmot teams

marmot metrics

marmot admin

marmot config

Tab Completion

Next Steps

Populating Your Catalog

Query Language

REST API

Deployment Options

Need Help?

Looking for Ingestion?

Installation​

Homebrew

Install script

Download the binary

Make it executable

Move to your PATH

Authentication​

Browser Login (Recommended)​

API Keys​

Auth Priority​

Contexts​

Configuration​

CLI Flags​

Environment Variables​

Config File​

Output Formats​

Commands​

marmot login​

marmot logout​

marmot context​

marmot assets​

marmot search​

marmot glossary​

marmot runs​

marmot lineage​

marmot users​

marmot apikeys​

marmot teams​

marmot metrics​

marmot admin​

marmot config​

Tab Completion​

Next Steps​

Populating Your Catalog

Query Language

REST API

Deployment Options

Need Help?

Installation

Authentication

Browser Login (Recommended)

API Keys

Auth Priority

Contexts

Configuration

CLI Flags

Environment Variables

Config File

Output Formats

Commands

marmot login

marmot logout

marmot context

marmot assets

marmot search

marmot glossary

marmot runs

marmot lineage

marmot users

marmot apikeys

marmot teams

marmot metrics

marmot admin

marmot config

Tab Completion

Next Steps