Skip to main content
DocumentationLibraryReference
On this page

Developers Command-line workflows

Check a query from the terminal

Check that the CLI reaches your Kater API and warehouse, list what a query reads, and preview its rows, in three commands.

Audience
Data teams
Prerequisites
  • The Kater CLI, signed in with kater login
  • A local copy, made with kater git clone

This is the first thing to do in a new local copy, and the first thing to do when something looks wrong. If you know dbt, the commands work the same way: kater debug checks the setup, kater ls lists what a selection selects, and kater show previews rows.

The commands and their times are real. Long waits are shortened in the recording.

  1. Check the setup.

    Run kater debug in your local copy. It checks the CLI, your profile and target, the project, the Kater API, your sign-in, each warehouse and the compile cache. It sends select 1 to every warehouse at once, through the Kater API.

    Terminal window
    cd ~/kater
    kater debug
    15:02:37  Running with kater=0.1.0, profile=kater, target=dev (Kater API at http://127.0.0.1:8788)
    15:02:37  kater 0.1.0, Python 3.14.3 ............................................. [OK]
    15:02:37  Profile kater in ~/.kater/profiles.yml, target dev ........................ [OK]
    15:02:37  Project kater_project.yml at ~/kater ...................................... [OK]
    15:02:38  Kater API 0.1.0 at http://127.0.0.1:8788 .................................. [OK]
    15:02:38  Signed in as you@example.com .............................................. [OK]
    15:02:39  Waiting for 2 warehouses to answer select 1. 1s
    15:02:42  Warehouse duckdb_sample ................................................. [SKIP]
    15:02:42    Kater stores no credential for the connection duckdb_sample.
    15:02:42  Warehouse snowflake_prod_connection (select 1) ............................ [OK]
    15:02:42  Content root on main, 0 files changed ..................................... [OK]
    15:02:43  Compile cache ~/.cache/kater-query-server, 1.5 GB ......................... [OK]
    15:02:43  All checks passed!

    A SKIP is a connection that has no stored credential yet. It does not fail the check. Your computer never holds a warehouse credential: every statement goes through your Kater API.

  2. List what a query reads.

    kater ls prints one line for each model that a selection selects, and sends nothing to the warehouse. A + before the name adds everything the query reads.

    Terminal window
    kater ls --select +spend_by_platform
    db_dataset.facebook_ads__account_report
    db_dataset.facebook_ads__ad_report
    db_dataset.google_ads__ad_report
    db_dataset.tiktok_ads__ad_report
    kater_dataset.facebook_ads__account_report
    kater_dataset.facebook_ads__ad_report
    kater_dataset.google_ads__ad_report
    kater_dataset.tiktok_ads__ad_report
    semantic.ad_reporting
    chart.spend_by_platform
    query.spend_by_platform
    path:connections/snowflake_prod_connection/workspaces/ad_reporting/workspace.sql,workspace.ad_reporting

    Each line is a selection that you can give to --select as it is. A model whose kind and name are used two times, as two connections can each have a workspace ad_reporting, also names its file. Add --output path to see each file, or --output json for the whole node.

  3. Preview the rows.

    kater show runs one query on the warehouse and prints its first rows, with the column names the query gives them.

    Terminal window
    kater show --select query.spend_by_platform --limit 5
    Previewing node 'spend_by_platform':
    | PLATFORM     | UNION__CURRENCY | SUM__SPEND |
    | ------------ | --------------- | ---------- |
    | facebook_ads | USD             | 876034.94  |
    | google_ads   | USD             | 1627324.59 |
    | tiktok_ads   | USD             | 232346.09  |
  • kater debug ends with “All checks passed!”.
  • kater ls --select +NAME lists the query and the models it reads.
  • kater show --select query.NAME --limit 5 prints rows with named columns.

If something looks wrong

You seeWhat to do
Kater could not reach the Kater API at URL.The Kater API is not running, or the target’s api_url is wrong. Check the target in ~/.kater/profiles.yml, then run kater debug again.
You are not signed in to the Kater API at URL.Run kater login.
Warning: --select spend_by_platfrom matches no object. Did you mean spend_by_platform?The name has a typo. Use the name it suggests.
A line such as Waiting for Kater to read the project. 11sKater reads the project’s files before it selects. The first time after a large change, this can take some seconds. The line shows that it still works.
--select facebook_ads__account_report selects 2 modelskater show shows one model. Give its typed address, such as kater_dataset.facebook_ads__account_report.

Next steps