kater admin connection create

Adds a Snowflake connection to Kater through Kater's API, and tests it.

Kater writes the connection’s connection.yaml, the folders that Kater gives a connection, and your own folder in it. It stops when the connection already exists.

Examples

# Add a Snowflake connection with a key pair. Kater asks for the key's passphrase
kater admin connection create snowflake_prod_connection --account myorg-myaccount --warehouse COMPUTE_WH --role SYSADMIN --user kater_service --private-key-file ~/.ssh/kater_key.p8 --schema DEMO_DB.ANALYTICS_AD_REPORTING
# Add a Snowflake connection that signs in with a password. Kater asks for the password
kater admin connection create snowflake_prod_connection --account myorg-myaccount --warehouse COMPUTE_WH --user kater_service --password --schema DEMO_DB.ANALYTICS_AD_REPORTING
# Print the connection.yaml that it would write, and save nothing
kater admin connection create snowflake_prod_connection --account myorg-myaccount --warehouse COMPUTE_WH --role SYSADMIN --database DEMO_DB --schema DEMO_DB.ANALYTICS_AD_REPORTING --dry-run

Arguments

Argument	Description
`<connection-name>`	The connection’s name, in lower snake case, such as `snowflake_prod_connection`. It is also the name of its folder under `connections/`.

Options

Option	Description
`--label <text>`	A name for people to read, such as `Snowflake production`.
`--description <text>`	Notes about the connection.
`--query-timeout <seconds>`	Sets `query_timeout`, the seconds that a query may run. Kater records it, but does not use it yet. Kater writes `300` when you leave it out.
`--query-timezone-conversion <text>`	Sets `query_timezone_conversion`. Kater records it, but does not use it yet. Kater writes `do_not_convert`, the usual value, when you leave it out.
`--dry-run`	Prints the `connection.yaml` that it would write, and saves nothing.
`--warehouse-type <type>`	The warehouse that the connection is on: `snowflake`, the default. It decides which settings options the connection takes, and how Kater reads names.
`--no-test`	Not available. Kater always tests a connection before it stores the credential.
`--database <database>`	A database to read, such as `shop`. Add `=` and an IANA timezone to set its timezone, such as `shop=UTC`. Without a timezone, it is `UTC`. You can give it more than one time.
`--schema <database.schema>`	A schema to read, such as `shop.sales`. A database that you leave out is in `UTC`. With `--dry-run`, give its database with `--database` too. You can give it more than one time.
`--table <database.schema.table>`	A table to read, such as `shop.sales.orders`. A schema with tables listed reads only those tables. Give its schema with `--schema` too. You can give it more than one time.
`--user <user>`	Snowflake only. The user that Kater signs in as.
`--private-key-file <file>`	Snowflake only. A PEM private key file, for key-pair sign-in. Add `--passphrase` when the key has one.
`--passphrase`	Snowflake only. Says that the key has a passphrase. You type it in a browser page, and Kater stores it.
`--password`	Snowflake only. Signs in with a password. You type it in a browser page, and Kater stores it.
`--prompt`	Snowflake only. Asks for the password or the passphrase at a hidden prompt in this terminal, not in a browser page. Use it on a machine with no browser, such as one you reach over SSH.
`--auth-method <method>`	Snowflake only. How the credential signs in: `username_password` or `key_pair`. Kater writes `username_password` when you leave it out.
`--account <account>`	Snowflake only. The account identifier, such as `myorg-myaccount`. Kater writes it as `snowflake_account_id`.
`--warehouse <warehouse>`	Snowflake only. The warehouse that runs queries, such as `COMPUTE_WH`.
`--role <role>`	Snowflake only. The role that queries run as, such as `SYSADMIN`. Leave it out to use the user’s default role.

It also takes the global options --json, --kater-root, --scope and --help.

Where Kater saves the connection

Only Kater’s API makes a connection. Run kater login first. Give --account, --warehouse and --user, and --private-key-file or --password. With --password or --passphrase, Kater opens a page on 127.0.0.1 in your browser, where you type the secret. A wrong secret shows its error on the page, and you try again. Any other error closes the page, and the command stops with it. With --prompt, Kater asks in the terminal. The secret is never a flag’s value or an environment variable, so an agent that runs the command does not see it.
Kater tests the sign-in, stores the credential on its server, and saves connection.yaml in Kater. Run kater git pull to get it in your local copy. This needs the settings:manage permission.
Kater uses every option of the connection. That includes the label, the description, the query settings, each database’s timezone and the tables. Kater refuses --no-test, --kater-root and --scope, a --database that no --schema selects, and an --auth-method that does not match the credential you give.
Names must match the warehouse. Give each database and schema as the warehouse spells it, such as DEMO_DB.ANALYTICS_AD_REPORTING.
--dry-run only prints. It needs no sign-in, and it ignores --user, --private-key-file, --passphrase, --password and --prompt.

What it writes

connection.yaml comes first, so --dry-run prints it.
connection_context.md and the agent library, ai_tools/.
Your own folder in the connection, such as users/you@example.com/, with its about.md, brainstorm/ and ai_tools/agents/, skills/ and workflows/.
Each modeling/ folder appears with its first model or test.

The test

Before it saves anything, Kater tests the connection. When the test fails, nothing is saved. When a warehouse setting is missing, the command stops and names each one. See Warehouse settings.