ReferenceCLI

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 --help

Install

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 version

When 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>:

VerbWhat it does
ls (or list)List resources of a type
getShow one resource
addCreate a resource
updateChange a resource
rmDelete a resource
setSet 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

CommandWhat it doesMain options
cred signupCreate 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 logoutSign 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 statusShow 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 tokenPrint 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

CommandWhat it doesMain options
cred initSet 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 devStart 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 mcpServe 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

CommandWhat it doesMain options
cred publishPublish 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 packageList 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, .env files, keys and certificates;
  • .git/, node_modules/, and the files cred init writes (.credible/, .mcp.json, CLAUDE.md, AGENTS.md, .claude/, .agents/, .cursor/);
  • anything listed in a .credignore file beside publisher.json: one path or glob per line, # for comments. notes.md or tests/ match at any depth, /docs only 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

CommandWhat it doesMain options
cred ls environmentList 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

CommandWhat it doesMain options
cred ls connectionList 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.

CommandWhat it doesMain options
cred ls databaseList 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

CommandWhat it doesMain options
cred ls groupList 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

CommandWhat it doesMain options
cred ls permissionList 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:

ScopeRoles
Organizationadmin, modeler, member
Environmentadmin, modeler, viewer
Packageviewer
# Let a CI group publish to one environment
cred add permission group:ci-publish modeler --environment analytics

What 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.

CommandWhat it doesMain 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

OptionWhereWhat it does
-h, --helpAnywhereHelp for the CLI, or for the command before it
-V, --cli-versionBefore a commandPrint the CLI version
--non-interactiveBefore a commandNever prompt (see below)
--cell <cell>Before or after a commandRun this one command against another cell
-y, --yesAfter a commandSkip confirmation prompts
--debugAfter a commandPrint debug output
--page, --page-sizeAfter a paged ls commandReturn 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 to jq.
  • No prompts without a terminal. The CLI never waits for input when stdin isn't a terminal, when CI or CRED_NON_INTERACTIVE is 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 codeMeaning
0Success
1The command failed, including when you aren't signed in
2The 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.

Next Steps

On this page