CLI
Every user-facing cred command and its main options, for signing up and in, local modeling, publishing, environments, connections, databases, groups, permissions, API keys and builds
The Credible CLI, cred, runs Credible from a terminal, from CI and from coding agents. Below is every command, with its purpose and main options. To set up a directory for local modeling with cred init, start with Cred CLI. For the full options of any command, run its help, which always matches your installed version.
cred --help
cred <command> --help # e.g. cred publish --help
cred <verb> <resource> --help # e.g. cred add connection --helpInstall
The CLI needs Node.js 20 or later. Install it from npm as @credibledata/cred-cli (opens in a new tab):
npm install -g @credibledata/cred-cli
cred -V # print the installed versionWhen a newer version is published, commands print a notice on stderr.
Shell completion. cred --install adds tab completion to your bash, zsh or fish profile, and cred --cleanup removes it. Completion knows command names, resource types and, for some commands, your environment and package names.
How Commands Are Named
Commands that act on a Credible resource read cred <verb> <resource>:
| Verb | What it does |
|---|---|
ls (or list) | List resources of a type |
get | Show one resource |
add | Create a resource |
update | Change a resource |
rm | Delete a resource |
set | Set a local default; sends no request |
Common actions also have short forms that run the same code: cred publish (cred add version), cred archive and cred unarchive (cred update version --archived / --no-archived), cred rerun (cred add run), and cred cancel-run (cred update run --cancel).
Commands act on your current organization and environment, which cred status shows. In a directory set up with cred init, they use that directory's saved organization and environment instead.
Sign In and Session
| Command | What it does | Main options |
|---|---|---|
cred signup | Create a Credible organization: sign in, open the signup page, and select the new organization once it exists. Prints the organization's name on stdout | --no-browser: print the signup URL instead of opening it; --no-wait: print the URL and exit at once, then run cred login <organization> after signing up; --timeout <minutes>: how long to wait (default 15) |
cred login [organization] | Sign in through your browser. Leave out the organization to pick from yours after signing in. No organization yet? Run cred signup | -c, --cluster <gcp|aws>: the cluster your organization runs on; --no-browser: print the sign-in URL instead of opening a browser; --force: sign in again, for example as someone else |
cred logout | Sign out of one cell (see below); other cells stay signed in | |
cred set cell <cell> | Set the cell your commands act on by default | |
cred status | Show the active organization, environment and token freshness and, in a directory set up with cred init, whether its local Publisher is running | --json: one JSON document on stdout |
cred token | Print a current access token on stdout, renewing it first if needed, for curl or another tool | |
cred set-access-token <jwt> | Authenticate with a group access token instead of a browser login, for CI and scripts | -o, --organization <name> |
The CLI renews your session before each command when it is close to expiring. Run cred login again only when a command tells you to.
Cells. A cell is one Credible deployment, such as production (the default) or a dedicated cluster. The CLI keeps a separate sign-in for each cell. --cell <cell>, before or after any command, picks the cell for that one command and isn't saved; cred set cell <cell> saves the default, and a directory set up with cred init can pin its own cell, which overrides it. cred --help lists the cells your version knows.
Local Modeling
| Command | What it does | Main options |
|---|---|---|
cred init | Set up a directory for local Malloy modeling: sign in if needed, choose an organization and environment, write the agent files, install the modeling skills, and start a local Publisher | -o, --organization, -e, --environment, --create-environment, --connections <all|none|names>, --skills <replace|keep|none>, --package <dir>, --port <number>, --no-start, --no-open, -d, --directory <path> |
cred dev | Start the directory's local Publisher in the foreground, running the cred init setup first if it hasn't run | -o, -e, --create-environment, --package, --skills, --connections, --port, --no-open, -y, --yes |
cred mcp | Serve the directory's local Publisher to an agent over stdio, starting it if needed. The .mcp.json that cred init writes runs this; you don't need to |
What each option does, the files cred init writes, and how skills stay current: Cred CLI.
Publish and Manage Versions
| Command | What it does | Main options |
|---|---|---|
cred publish | Publish the package in the current directory as a new version | --dry-run: list the files that would be uploaded and the ones left out, and upload nothing. It still needs publisher.json, warns about data files over 1 MB and fails if the package is over 50 MB, but doesn't compile the model; --set-latest: make it latest now, before its tables and indexes are built; --json; -y |
cred ls version <package> | List a package's versions | |
cred get version <package> <version> | Show a version's build status, indexing progress, and whether it is waiting to become latest | --wait: poll until the build ends; --timeout, with --wait |
cred archive <package> <version> | Archive a version | -y |
cred unarchive <package> <version> | Bring an archived version back | -y |
cred ls package | List the packages in the environment | --page, --page-size |
cred get package <package> | Show the latest version, its index status, and whether new versions become latest automatically | |
cred update package <package> | Change a package | --version <id>: set the latest version; --description <text> |
cred rm package <package> | Delete a package | -y |
What cred publish Uploads
publisher.json in the current directory must have a name and a version. A published version can't be replaced, so raise version to publish again. The CLI checks the package against the upload size limit before sending it.
Every file under the directory is uploaded except:
- credential and local-setup files, such as
publisher.config.json,.envfiles, keys and certificates; .git/,node_modules/, and the filescred initwrites (.credible/,.mcp.json,CLAUDE.md,AGENTS.md,.claude/,.agents/,.cursor/);- anything listed in a
.credignorefile besidepublisher.json: one path or glob per line,#for comments.notes.mdortests/match at any depth,/docsonly at the top. A!line can't bring a file back.
cred publish --help prints the exact list for your version, and cred publish --dry-run shows the result for your directory: files to upload on stdout, files left out on stderr. Without --set-latest, a package with auto-promote on makes the version latest when its tables and indexes are built. See Publishing and Versions.
cred get version reports buildStatus as BUILDING until it ends at READY, FAILED, or UNSUPPORTED (materialized sources on a database that can't be materialized, which are then queried live).
Resource Management
Environments
| Command | What it does | Main options |
|---|---|---|
cred ls environment | List environments | --page, --page-size |
cred get environment <name> | Show an environment | |
cred add environment <name> | Create an environment (organization admins only) | --readmeFile <path> |
cred update environment <name> | Change an environment | --git-modeling <true|false> with --git-repository-owner, --git-repository-name and --git-base-branch, for a git-backed environment |
cred rm environment <name> | Delete an environment | -y |
cred set environment [name] | Set the CLI's default environment. Leave out the name to pick from a list. Changes nothing in the Credible App |
Connections
| Command | What it does | Main options |
|---|---|---|
cred ls connection | List the environment's connections | --page, --page-size |
cred add connection <file> | Create the connections in a JSON file | --include-tables <tables>: the tables to make searchable, as {dataset/schema}.{table}, comma-separated; without it, none are; --skip-indexing; -y |
cred add connection --from-publisher-config [dir] | Copy connections from a local Publisher's publisher.config.json. Each is tested from Credible before it is created | --name <connection>, repeatable |
cred update connection <file> | Change fields of existing connections, such as a rotated password or key | -y |
cred rm connection <name> | Delete a connection | -y |
The file for add connection is a JSON array. Each entry has a name, a type (postgres, bigquery, snowflake, trino, databricks, mysql, sqlserver, duckdb, motherduck or ducklake), and an object named after the type that holds the database's settings:
[
{
"name": "warehouse",
"type": "postgres",
"postgresConnection": {
"host": "db.example.com",
"port": 5432,
"databaseName": "analytics",
"userName": "credible_readonly",
"password": "..."
}
}
]The other settings objects are bigqueryConnection, snowflakeConnection, sqlserverConnection and so on. Each database's page under Connect Data has its entry and what each field means, and the full schema is in the Admin API Reference. Connection names may contain only letters, numbers and underscores, and must start with a letter or underscore. Credible tests each connection before creating it, and add connection refuses a connection that fails its test or a name the environment already has. See Connect from the CLI.
For update connection, each entry names a connection and holds only the fields that change; everything else is kept. To rotate a Snowflake password:
[{ "name": "warehouse", "snowflakeConnection": { "password": "new-password" } }]Databases and Tables
A database is a Credible-managed DuckLake in the current environment. Models read its tables as <database>.table('<table>'), and #@ persist storage=<database> builds into it. See Where Tables Are Built.
| Command | What it does | Main options |
|---|---|---|
cred ls database | List the environment's databases | --page, --page-size |
cred get database <database> | Show a database: status, whether it's the default, size, storage GB-hours and compute time this month | |
cred add database <database> | Create a database. The name is a lowercase letter, then lowercase letters, digits or _ | --description <text>; -y |
cred update database <database> | Change a database's description | --description <text> |
cred rm database <database> | Delete a database and every table in it. Nothing can be recovered, and the default database can't be deleted | -y |
cred ls table <database> | List a database's tables, with each one's status and source | --page, --page-size |
cred get table <database> <table> | Show a table: status, columns, row count, size, source file, and a failed load's error | |
cred add table <database> <files...> | Load local files (CSV, Parquet, XLSX or JSON) as tables, one table per file. Exits 1 if any file fails to load | --name <table> (one file only); --replace: replace an existing table, which keeps serving until the new file loads; --sheet <name>; --format <csv|parquet|xlsx|json>; --option <key=value>, repeatable: header, delimiter, skip |
cred rm table <database> <table> | Delete a table. Its files stay recoverable for 7 days | -y |
Groups, Members and API Keys
| Command | What it does | Main options |
|---|---|---|
cred ls group | List the organization's groups | |
cred get group <group> | Show a group | |
cred add group <group> | Create a group | -d, --description |
cred rm group <group> | Delete a group | -y |
cred add member <group> <user|group> <name> <admin|member> | Add a user, or a nested group, to a group | |
cred rm member <group> <user|group> <name> | Remove a member | |
cred add group-access-token <group> <token-name> | Create an API key that acts as the group. The key is printed once | -e, --expires-at <ISO 8601 date>; -j, --json-output |
cred ls group-access-token <group> | List a group's API keys | |
cred rm group-access-token <group> <token-name> | Revoke an API key | -y |
An API key acts with every role its group holds; there are no per-key scopes. See REST APIs.
Permissions
| Command | What it does | Main options |
|---|---|---|
cred ls permission | List grants on the organization, an environment or a package | --environment, --package |
cred get permission <who> | Show one grant | --environment, --package |
cred add permission <who> <role> | Grant a role | --environment, --package, --notifyPeople |
cred rm permission <who> | Revoke a grant | --environment, --package, -y |
<who> is user:<email> or group:<name>. With no --environment or --package, the grant is on the organization, and rm permission removes only the organization grant. Roles by scope:
| Scope | Roles |
|---|---|
| Organization | admin, modeler, member |
| Environment | admin, modeler, viewer |
| Package | viewer |
# Let a CI group publish to one environment
cred add permission group:ci-publish modeler --environment analyticsWhat each role allows is on Permissions.
Builds: Materializations, Pre-aggregates, Indexes and Runs
These commands show and control what Credible builds for a published version: materialized tables, pre-aggregates and search indexes.
| Command | What it does | Main options |
|---|---|---|
cred ls materialization <package> <version> | List materialized sources, with status and any failure reason | |
cred get materialization <package> <version> <id> | Show one: status, physical table, freshness | |
cred ls preaggregate <package> <version> | List pre-aggregated measures, with status and freshness | --source |
cred get preaggregate <package> <version> <id> | Show one | |
cred ls index <package> <version> | List search indexes, with status and freshness | --page, --page-size |
cred get index <package> <version> <id> | Show one | |
cred ls run <package> [version] | List build runs, most recent first | --source, --dimension, --measure |
cred get run <package> <run-id> | Show a run and the state of each unit it built | |
cred rerun <package> <version> | Start a build of a version. Without options it rebuilds everything | --source, --dimension or --measure: build one unit; --include-upstream; --model-file |
cred cancel-run <package> <run-id> | Cancel a run in progress | -y |
With cred get, materialization and preaggregate can be shortened to mat and preagg. The other verbs need the full names.
Common Options
| Option | Where | What it does |
|---|---|---|
-h, --help | Anywhere | Help for the CLI, or for the command before it |
-V, --cli-version | Before a command | Print the CLI version |
--non-interactive | Before a command | Never prompt (see below) |
--cell <cell> | Before or after a command | Run this one command against another cell |
-y, --yes | After a command | Skip confirmation prompts |
--debug | After a command | Print debug output |
--page, --page-size | After a paged ls command | Return one page. By default every record is returned |
Options that belong to a command go after it: cred rm package sales -y works, cred -y rm package sales doesn't.
Scripts, CI and Agents
- Output. Data goes to stdout (
cred status --json,cred ls ...,cred token); progress, warnings and errors go to stderr, so stdout can be piped tojq. - No prompts without a terminal. The CLI never waits for input when stdin isn't a terminal, when
CIorCRED_NON_INTERACTIVEis set, or with--non-interactive. A command that needs an answer stops and names the flag that gives it. - Authentication. Create a group access token, store it as a CI secret, and run
cred set-access-token "$TOKEN" -o <organization>before other commands. The CI/CD template does this.
| Exit code | Meaning |
|---|---|
0 | Success |
1 | The command failed, including when you aren't signed in |
2 | The command needed an answer it couldn't ask for, or an option had a value it doesn't accept. The error names the flag to pass |
Older CLI versions used project for what is now an environment. cred ls project and the other project forms still work and print a deprecation warning; use environment.