> ## Documentation Index
> Fetch the complete documentation index at: https://docs.credibledata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Everything the Credible App manages, scriptable from your terminal

The Credible CLI (`cred`) puts the platform in your terminal. Everything the Credible App manages is scriptable — the same environments, packages, connections, and groups — which makes the CLI the natural building block for automation and [CI/CD](/platform-admin/cicd).

## Installation

<Note>
  **Prerequisites**: Node.js version 20+ and npm package manager
</Note>

Install the Credible CLI globally from the npm registry:

```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
npm install -g @credibledata/cred-cli
```

View package details at [npmjs.com/package/@credibledata/cred-cli](https://www.npmjs.com/package/@credibledata/cred-cli)

### Shell Autocompletion

The CLI supports bash/zsh autocompletion. To set it up, run:

```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
cred --install
```

Restart your shell, then type `cred ` + TAB to see available commands, or `cred ls ` + TAB to see resource types. Completion is context-aware — `cred set environment ` + TAB completes your environment names, and `cred ls version ` + TAB completes your package names. To remove it, run `cred --cleanup`.

## Core Commands

### Authentication & Session

#### Login

Authenticate with your organization via Auth0:

```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
cred login <organizationName> [-c gcp|aws]
```

Options:

* `-c, --cluster <cluster>`: Target cluster (`gcp` or `aws`). Defaults to your organization's default cluster (`gcp` for most organizations)

#### Check Status

View your current organization and environment:

```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
cred status
```

#### Logout

Clear stored credentials:

```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
cred logout
```

#### Authenticate as a Service Account

For scripts and CI/CD, authenticate with a service account JWT instead of the browser-based login — for example, a [group access token](#resource-management):

```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
cred set-access-token <jwtToken> [-o <organizationName>]
```

Options:

* `-o, --organization <organizationName>`: Organization to set for the session

### Resource Management

<Tabs>
  <Tab title="Environments">
    #### List Environments

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred ls environment
    ```

    #### Get Environment Details

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred get environment <environmentName>
    ```

    #### Create Environment

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred add environment <environmentName> [--readmeFile <path>] [--replication <count>] [-y]
    ```

    Options:

    * `--readmeFile <path>`: Path to README file to include
    * `--replication <count>`: Replication count for the environment's packages (must be at least 1)

    #### Update Environment

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred update environment <environmentName> [--replication <count>] [-y]
    ```

    #### Delete Environment

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred rm environment <environmentName> [-y]
    ```

    #### Set Default Environment

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred set environment <environmentName>
    ```

    <Warning>
      Setting a default environment only applies to CLI sessions - it doesn't affect any web experiences
    </Warning>
  </Tab>

  <Tab title="Packages">
    #### List Packages

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred ls package
    ```

    #### Delete Package

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred rm package <packageName> [-y]
    ```

    #### Update Package

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred update package <packageName> [options]
    ```

    Options:

    * `--version <versionId>`: Set which version is latest/pinned
    * `--description <text>`: Update package description
    * `--replication <count>`: Set replication count (must be at least 1)

    <Note>
      The "latest" version may also be called "pinned" in the web UI
    </Note>

    #### Publish New Version

    Run from your package directory:

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred publish [--set-latest] [--replication <count>] [-y]
    ```

    Options:

    * `--set-latest`: Set the published version as the package's latest version
    * `--replication <count>`: The number of replicas to create

    #### List Package Versions

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred ls version <packageName>
    ```

    #### Archive Version

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred archive <packageName> <versionId> [-y]
    ```

    #### Unarchive Version

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred unarchive <packageName> <versionId> [-y]
    ```

    <Note>
      There is no `cred set package` command. Use `cred set environment` to set your default environment. Packages are managed through publish/archive/unarchive commands.
    </Note>
  </Tab>

  <Tab title="Connections">
    #### List Connections

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred ls connection
    ```

    #### Create Connection

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred add connection <connectionFileName> [--include-tables <tables>] [--exclude-tables <tables>] [--skip-indexing] [-y]
    ```

    Options:

    * `--include-tables <tables>`: Comma-separated list of tables to index for AI-assisted modeling, as `{dataset/schema}.{table}` (use `*` for all tables in a schema, e.g. `sales.*,finance.orders`)
    * `--exclude-tables <tables>`: Comma-separated list of tables to exclude from indexing (same format); mutually exclusive with `--include-tables`
    * `--skip-indexing`: Disable automatic indexing for this connection; cannot be combined with the table flags

    The `connectionFileName` should be a JSON file containing an array of connection objects. The connection name is a field within the JSON, not a command-line argument.

    **Command Syntax:**

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred add connection <connectionFileName>
    ```

    **JSON File Structure:**

    The file should contain an array of connection objects. Each connection has:

    * `name`: The connection name (required)
    * `type`: Connection type (`postgres`, `bigquery`, `snowflake`, `trino`, `databricks`, `mysql`)
    * Connection-specific configuration based on type

    **BigQuery Example:**

    ```json theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    [
      {
        "name": "my-bigquery-connection",
        "type": "bigquery",
        "bigqueryConnection": {
          "defaultProjectId": "my-project",
          "billingProjectId": "billing-project",
          "location": "us-central1",
          "serviceAccountKeyJson": "{\"type\":\"service_account\",\"project_id\":\"...\"}",
          "maximumBytesBilled": "1000000",
          "queryTimeoutMilliseconds": "30000"
        }
      }
    ]
    ```

    Note: For BigQuery, the `serviceAccountKeyJson` field contains the entire JSON content as a string (not a file path).

    **PostgreSQL Example:**

    ```json theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    [
      {
        "name": "my-postgres-connection",
        "type": "postgres",
        "postgresConnection": {
          "host": "localhost",
          "port": 5432,
          "databaseName": "mydb",
          "userName": "myuser",
          "password": "mypassword"
        }
      }
    ]
    ```

    Alternatively, you can use a connection string:

    ```json theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    [
      {
        "name": "my-postgres-connection",
        "type": "postgres",
        "postgresConnection": {
          "connectionString": "postgresql://user:password@localhost:5432/mydb"
        }
      }
    ]
    ```

    **Snowflake Example:**

    ```json theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    [
      {
        "name": "my-snowflake-connection",
        "type": "snowflake",
        "snowflakeConnection": {
          "account": "myaccount.us-east-1",
          "username": "myuser",
          "password": "mypassword",
          "warehouse": "COMPUTE_WH",
          "database": "MYDB",
          "schema": "PUBLIC",
          "responseTimeoutMilliseconds": 60000
        }
      }
    ]
    ```

    **Databricks Example (Personal Access Token):**

    ```json theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    [
      {
        "name": "my-databricks-connection",
        "type": "databricks",
        "databricksConnection": {
          "host": "dbc-xxxxxxxx-xxxx.cloud.databricks.com",
          "path": "/sql/1.0/warehouses/abcdef1234567890",
          "token": "dapiXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "defaultCatalog": "main",
          "defaultSchema": "default"
        }
      }
    ]
    ```

    Alternatively, authenticate with an OAuth M2M service principal:

    ```json theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    [
      {
        "name": "my-databricks-connection",
        "type": "databricks",
        "databricksConnection": {
          "host": "dbc-xxxxxxxx-xxxx.cloud.databricks.com",
          "path": "/sql/1.0/warehouses/abcdef1234567890",
          "oauthClientId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "oauthClientSecret": "doseXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "defaultCatalog": "main",
          "defaultSchema": "default"
        }
      }
    ]
    ```

    See the [Databricks connection reference](/reference/connections/databricks) for details on creating a SQL warehouse and credentials.

    <Note>
      The connection name is defined in the JSON file itself, not as a command argument. Names can contain only letters, numbers, and underscores, and must start with a letter or underscore. You can include multiple connections in a single JSON file array.
    </Note>

    #### Delete Connection

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred rm connection <connectionName> [-y]
    ```
  </Tab>

  <Tab title="Groups">
    #### List Groups

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred ls group
    ```

    #### Get Group Details

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred get group <groupName>
    ```

    #### Create Group

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred add group <groupName> [-d <description>] [-y]
    ```

    Options:

    * `-d, --description`: Description for the group
    * `-y, --yes`: Skip confirmation

    #### Delete Group

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred rm group <groupName> [-y]
    ```

    #### Create Group Access Token

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred add group-access-token <groupName> <tokenName> [-e <expiresAt>] [-j]
    ```

    Arguments:

    * `<groupName>`: The name of the group
    * `<tokenName>`: Name for the API key/token

    Options:

    * `-e, --expires-at <expiresAt>`: Token expiration date in ISO 8601 format (e.g., `2027-12-31T23:59:59Z`); defaults to no practical expiration
    * `-j, --json-output`: Output only JSON, for use in scripts

    **Example:**

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred add group-access-token ai-agents-group production-token
    ```

    This command generates an API key that can be used to authenticate applications or services with the permissions of the specified group. The token is displayed once and should be stored securely.

    #### List Group Access Tokens

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred ls group-access-token <groupName>
    ```

    #### Delete Group Access Token

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred rm group-access-token <groupName> <tokenName> [-y]
    ```

    #### Add Member to Group

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred add member <groupName> <memberType> <memberName> <role>
    ```

    Arguments:

    * `<groupName>`: The name of the group
    * `<memberType>`: Type of member (`user` or `group`)
    * `<memberName>`: Name of the user or group to add
    * `<role>`: Member role (`admin` or `member`)

    **Examples:**

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    # Add a user as admin
    cred add member engineering-team user john.doe@example.com admin

    # Add a nested group as member
    cred add member engineering-team group data-analysts member
    ```

    #### Remove Member from Group

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred rm member <groupName> <memberType> <memberName>
    ```

    Arguments:

    * `<groupName>`: The name of the group
    * `<memberType>`: Type of member (`user` or `group`)
    * `<memberName>`: Name of the user or group to remove

    **Example:**

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred rm member engineering-team user john.doe@example.com
    ```

    <Note>
      Groups enable role-based access control (RBAC) for organizing users and managing permissions across environments and packages. Groups can contain both individual users and other groups (nested groups).
    </Note>
  </Tab>

  <Tab title="Materializations & Indexes">
    These commands monitor and manage the [materialized tables and search indexes](/how-to/modeling/persistence) the Credible service builds for a published package version.

    #### List Materializations

    List the materializations of a package version, with status and any failure reason:

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred ls materialization <packageName> <versionId>
    ```

    #### Get Materialization Details

    Status, physical table and connection, serving build, and freshness/staleness:

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred get materialization <packageName> <versionId> <materializationId>
    ```

    #### List Indexes

    List the dimensional search indexes of a package version, with status, any failure reason, and freshness:

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred ls index <packageName> <versionId>
    ```

    #### Get Index Details

    Status, row count, last indexed time, and freshness/staleness:

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred get index <packageName> <versionId> <indexId>
    ```

    #### List Runs

    List a package's build/refresh runs, most recent first. Runs are package-scoped and cover both materialized sources and dimensional indexes:

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred ls run <packageName> [versionId] [--source <sourceName>] [--dimension <dimension>]
    ```

    Options:

    * `[versionId]`: Filter to the runs a specific version initiated (e.g., `0.1.21`); omit to list every run in the package
    * `--source <sourceName>`: Only list runs targeting this persisted source
    * `--dimension <dimension>`: Only list runs targeting this indexed dimension

    #### Get Run Details

    Includes the run's build-plan graph — per-unit state, physical table names, and row counts:

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred get run <packageName> <runId>
    ```

    #### Trigger a Run

    Trigger an on-demand rebuild/refresh for a package version. Defaults to a full run (all sources and indexes):

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred rerun <packageName> <versionId> [--source <sourceName>] [--dimension <dimension>] [-y]
    ```

    Options:

    * `--source <sourceName>`: Scope the run to a single persisted source
    * `--dimension <dimension>`: Scope the run to a single indexed dimension
    * `--model-file <modelFilePath>`: Disambiguate a source/dimension defined in more than one model file
    * `--include-upstream`: Also force-rebuild the target's upstream persisted dependencies (only meaningful with `--source`/`--dimension`)

    #### Cancel a Run

    Cancel an in-flight run:

    ```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
    cred cancel-run <packageName> <runId> [-y]
    ```
  </Tab>
</Tabs>

## Command Options

### Global Options

| Option              | Description                                                                    |
| ------------------- | ------------------------------------------------------------------------------ |
| `-V, --cli-version` | Display the CLI version number                                                 |
| `-h, --help`        | Display help (use alone for general help or after a command for specific help) |
| `--debug`           | Enable debug output (most commands)                                            |
| `-y, --yes`         | Skip confirmation prompts                                                      |

### Pagination

List commands (`cred ls environment`, `cred ls connection`, `cred ls package`, `cred ls index`, `cred ls run`) return all records by default and accept:

| Option                 | Description               |
| ---------------------- | ------------------------- |
| `--page <number>`      | Page number (starts at 1) |
| `--page-size <number>` | Items per page (max: 500) |

<Note>
  Earlier CLI versions used `project` where the platform now uses `environment` (e.g., `cred ls project`). The `project` commands still work as deprecated aliases — use the `environment` forms going forward.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="CI/CD Setup" icon="rocket" color="#5C7A93" href="/platform-admin/cicd">
    Put the CLI to work — publish packages automatically on merge
  </Card>

  <Card title="API Access" icon="key" color="#94793A" href="/how-to/integrating/apis">
    Use group access tokens to authenticate applications with the REST APIs
  </Card>
</CardGroup>