CLI overview

Every Esker command, what it does, and where to learn more.

The CLI is installed by pip install esker (or uv add esker). Two equivalent entry points point at the same binary:

esker <cmd>
esk <cmd>      # short alias

esker (no args) prints help. Every subcommand accepts --help for its own usage.

Commands by job

Build a dataset

command	what
`esker list`	List pipelines registered in this project
`esker run <domain>`	Execute a pipeline, write parquet locally
`esker test [<domain>]`	Run fixtures against your `transform`
`esker check <domain>`	Diff your local schema against the last published one
`esker push <domain>`	Run, gate, and upload to the hub

Detailed reference: CLI authoring.

Consume a dataset

command	what
`esker pull <ref>`	Download a parquet, content-hash verify
`esker view <ref>`	One-screen summary: header + sample rows
`esker head <ref>`	Records, filterable with `--where`
`esker schema <ref>`	The schema as a typed table
`esker manifest <ref>`	The manifest as `key value` lines
`esker search <query>`	Find publishers of a name, or full-text search

Detailed reference: CLI reading.

Manage bindings

command	what
`esker add <owner>/<name>`	Bind a dataset, pin its version in `esker.lock`
`esker remove <name>`	Drop a binding
`esker sync`	Reconcile the cache against the lockfile
`esker upgrade <name>`	Re-resolve to the hub's latest version

Detailed reference: CLI bindings.

command	what
`esker login`	Browser sign-in
`esker logout`	Clear local credentials
`esker whoami`	Show signed-in user and active handle
`esker config set-owner <handle>`	Print a `pyproject.toml` snippet
`esker config set-handle <handle>`	Rename your handle (server-side)
`esker transfer <ref> <new_owner>`	Hand a dataset to another handle
`esker visibility <ref> public\|private`	Toggle dataset visibility (phase 1: public only)

Detailed reference: Auth.

Refs

Most read commands accept a ref — the address of a dataset on the hub. A ref can be:

form	meaning
`<owner>/<name>`	latest version published by `<owner>`
`<owner>/<name>@<version>`	a specific version
`<owner>/<name>@latest`	same as no version
`<name>` (bare)	resolved through your project's bindings

Bare names are the recommended path in code and CLI alike. They keep the owner choice in one explicit place (esker add) and the rest of your usage clean.

Output conventions

Esker's CLI is calm and dense. A successful command is two or three lines:

$ esker push us.treasury.yields
  archie/us.treasury.yields@2.0.0
  4,205 records · 0.7s · output/us.treasury.yields.parquet
  pushed archie/us.treasury.yields@2.0.0

Errors are two lines — the type and message in red, then a → file:line pointer in dim:

  ValueError: esker_id jurisdiction 'us' does not match DOMAIN_ID jurisdiction 'ca'
  → my_pipelines/sec_companies.py:34

Pass -v / --verbose to add the full traceback.

Every read command supports --json for piping into jq:

esker manifest archie/us.treasury.yields --json | jq '.content_hash'

The output is pretty-printed and newline-terminated.

Exit codes

0 — success.
1 — anything that prevents the command from completing. Specific failure mode is in the error message.

There are no other exit codes. Scripts can branch on $? cleanly.