Skip to main content
DocumentationLibraryReference
On this page

Guides

Organisation setup (Platform admins)

Install the CLI, set up the organisation, connect your warehouse, invite your team, set access and write back to GitHub.

Audience
IT and platform admins
Prerequisites
  • The Admin role in your Kater organisation
  • macOS or Linux, with an OS keychain, for the Kater CLI
  • A Snowflake account, warehouse, role and user for Kater, or a DuckDB file
  • Permission to install a GitHub App on the repository, only for GitHub write-back
Set up your Kater organisation so people sign in safely, read only what they should, and get answers from one governed copy of your definitions.

One person, two hats

In smaller teams, one person may own both platform admin and data team work. The guides are organised by responsibility, not job title.

Set up your organisation

The quickest way is one prompt to your agent, which does these steps with you in one chat: see Set up Kater. This page shows each step in detail. Follow its sections in order. Each one does one thing and ends with a result you can see.

  1. Install the CLI and sign in. Get the kater command and sign in to your organisation.
  2. Set up the organisation. Run kater init to make your content store and describe your company.
  3. Connect your warehouse. Make a connection, then sync its schemas.
  4. Invite your team. Add people with the right role, one by one or from a CSV file.
  5. Set who can read what. Restrict folders and grant them to people and groups.
  6. Write back to GitHub. Optional. Publish the shared layer to your own repository.
  7. Tell business teams to connect their agents. Each person connects their own agent from Ask.

To learn the words first, such as organisation, connection, role and access level, read Key concepts. What each role may do is in Users and roles.

Install the CLI and sign in

Every admin task on this page starts from the Kater CLI. Install it and sign in one time.

  1. Install the CLI.

    On macOS or Linux, the install script installs the CLI and adds it to your PATH. Open a new terminal after it. To install it with pipx, see Install and sign in.

    Terminal window
    curl -fsSL https://landing.kater.ai/install.sh | sh

  2. Sign in.

    kater login opens your browser to sign in, and saves the credential only in your OS keychain.

    Terminal window
    kater login

  3. Check who you are signed in as.

    kater auth status never shows a token. Its status is authenticated when Kater accepts your sign-in.

    Terminal window
    kater auth status

For automation, give your profile’s target an api_url and a token that reads the environment, such as token: "{{ env_var('KATER_CI_TOKEN') }}", instead of signing in. The token is never saved, and it expires, so it suits a short job that a person starts. See Install and sign in.

Check it worked

  • kater --version prints the version.
  • kater auth status reports authenticated.
  • kater debug checks the profile, the project, the sign-in and each warehouse, and ends with All checks passed!. Run it in a local copy, which holds kater_project.yml. Until kater init or kater git clone makes one, its Project check fails.

Set up the organisation

kater init walks you through the setup of your organisation. It saves its progress on the server, so you can stop at any time and run it again to continue. Your agent does the same steps from kater init guide, with one command for each step.

  1. Start the onboarding.

    Make a folder for your local work, then start it there.

    Terminal window
    mkdir kater-setup
    cd kater-setup
    kater init

  2. Set up the project.

    The first step makes your content store and its starting folders. Kater keeps your content there, in a git repository that nobody clones directly.

  3. Connect the warehouse, sync it and run a first query.

    Steps 2 to 4 test and store the Snowflake connection, sync the schemas you select, and read 5 rows from one synced Kater dataset. Connect your warehouse shows the connection and the sync in detail.

  4. Connect the Kater MCP.

    Step 5 adds the hosted Kater MCP to your agent, for every folder: kater init mcp --harness claude runs claude mcp add for Claude Code. Start your agent again and sign in to Kater. Kater completes the step when it sees your agent list the Kater MCP’s tools. Kater works through your agent, so this step is required.

  5. Describe your company.

    Step 6 asks for your company’s name, what the business does, who uses its data, and the questions or metrics that matter most. It writes them to the company about.md, which every agent reads before every answer. You can change it later in AI Tools › About you › About the company.

  6. Follow the other steps, or come back to them.

    The onboarding goes on with the steps in the table below. The other guides do each one too, so you can skip a step here and do it there.

#StepWhat it doesRequiredIts guide
1Set up the projectMakes your content store and its starting foldersYesThis page
2Connect your warehouseTests and stores the Snowflake connectionYesNew connection
3Sync schemasWrites the DB datasets and the Kater datasetsYesSchema sync
4Run a first queryReads 5 rows from one synced Kater datasetYes
5Connect the Kater MCPAdds the hosted Kater MCP to your agent, for every folder. Kater completes it when it sees your agent list its tools.YesConnect your agent
6Describe your companyWrites the company about.md that every agent readsNoThis page
7Invite your teamInvites people, a CSV file, SSO or SCIMNoInvite your team
8Make a local copy hereRuns kater git cloneNoData teams
9Install the editor extensionRuns kater vscode installNoData teams
10Write back to GitHubRuns kater admin write-back connectNoWrite back to GitHub
11Give your agent the local copyWrites the local Kater MCP into the local copy, which reads the copy’s files, and names the first skill to follow. It starts no agent.NoData teams

Only admins can run the onboarding, and one admin at a time. --takeover continues a run that another admin started. --reset clears the progress only, and removes nothing that you set up. The Get started card in the portal’s sidebar shows the same steps under Organization setup (Admin), first until the setup is complete. A connection that you make in Settings › Connections, or an invitation that you send from Manage users, also marks its step.

The Get started checklist with the organisation's setup steps
Setup progress in the Get started card.

Check it worked

  • When every step is done, the onboarding prints: “Kater is set up. Open app.kater.ai to see your data, or run kater agent to keep modelling.”
  • AI Tools › About you › About the company shows what you wrote about your company.

Invite your team

Add the people who use Kater, each with one role. Viewer is the default, the role with the fewest permissions.

Each person has one role: Admin, Developer or Viewer. A data team member who changes the shared layer needs Developer. See what each role may do in Users and roles.

  1. Select New user.

    In the admin console, open Settings › Users and select New user.

  2. Fill in the person, the role and the connections.

    Enter the email, and the name if you want to. Select the role. For a Viewer or a Developer, select at least one connection: they see no data without one. The first connection you select is their default.

    The New user dialog filled in, with the email, the Developer role and one connection
    New user, filled in.

  3. Select Send invitation.

    Kater sends an invitation email. The person selects their own password when they accept it, and their personal folder appears in each connection they can use at their first sign-in.

See Manage users.

  1. Invite people by email.

    Terminal window
    kater admin team invite sam@example.com lee@example.com --role developer --group Marketing

  2. Or invite from a CSV file.

    Terminal window
    kater admin team invite --csv people.csv
    people.csv
    email,name,role,groups,attributes
    sam@example.com,Sam Lee,viewer,Marketing;Leadership,department=Marketing

Anyone already invited or already a member is skipped. kater init offers the same in its Invite your team step.

Single sign-on and SCIM

  • kater admin sso link makes a 7-day link that your IT team uses to connect your identity provider.
  • kater admin scim request asks Kater to switch on SCIM provisioning for your organisation.

See Users and roles.

Check it worked

  • Settings › Users lists each person with the right role.
  • Each person is in the right groups. See Permissions and groups.

Set who can read what

Access works like a shared drive. A new organisation starts with Everyone as Viewer, with execute, on the whole content store, except connections/: a connection is open only to the people and groups granted it. Limit only the folders that need it.

Each person’s personal folder is private to them, and admins always keep full access. A folder you restrict keeps out everyone it does not list. You then grant people or groups a level: Viewer, Editor or Manager. See Files and access for every rule.

  1. Open the folder’s access.

    In the admin console, open Files & access, select the folder, then select Manage access.

  2. Restrict it.

    Under general access, select Restricted.

  3. Grant it.

    Type in Add people or groups, select a level, then select Share.

  1. See who has access.

    Terminal window
    kater admin access show connections/snowflake_prod_connection/workspaces/ad_reporting

  2. Restrict the folder.

    Terminal window
    kater admin access restrict connections/snowflake_prod_connection/workspaces/ad_reporting

  3. Grant it.

    Terminal window
    kater admin access grant connections/snowflake_prod_connection/workspaces/ad_reporting --level editor --group Marketing

Run kater admin access in your own terminal. Agents and the Files terminal refuse it.

Check it worked

  • Files & access marks the folder Restricted.
  • kater admin access show PATH lists the grants you gave, and Organisation admins.

Write back to GitHub

Write-back publishes each connection’s modeling/ folder, the shared layer and the DB datasets it reads, to a GitHub repository. It is one-way: Kater never reads anything back from GitHub.

  1. Connect a repository.

    Kater asks you to authorize its GitHub App, then for the repository, the folder and the schedule. on_publish writes back about a minute after each publish.

    Terminal window
    kater admin write-back connect --path-prefix kater/ --schedule on_publish

  2. Check it.

    kater admin write-back status shows the repository, its folder and schedule, the last run and the open pull request.

    Terminal window
    kater admin write-back status

  3. Merge the pull request.

    Each run pushes the branch kater/shared as one commit, and opens or updates one pull request into main, titled “Kater: shared layer”.

Change the shared layer in Kater, not in GitHub. The next pull request undoes an edit made directly in the repository’s kater/ folder. If you disconnect, what is already in GitHub stays. Run kater admin write-back in your own terminal. See Content store and GitHub write-back.

Check it worked

  • kater admin write-back status names your repository and its schedule.
  • A pull request into main opens about a minute after a publish.

Readiness checklist

Before your team begins, confirm:

  • kater init reports that Kater is set up.
  • The Snowflake role reads only the databases and schemas Kater should model, with USAGE on one warehouse.
  • connection.yaml lists only the intended databases and schemas, and its id is unchanged.
  • kater sync --check exits 0.
  • If you want nightly syncs, the sync job is enabled and the cron line is installed.
  • Your team is invited with the right roles and groups.
  • Restricted folders have the right grants, and personal folders stay private.
  • If you use write-back, a pull request into main opens after a publish.
  • Profile › AI app shows your organisation’s MCP address, in Connect your agent.

Next steps