CLI

tdk and tdkserver are the command-line clients for Tabsdata. tdkserver allows users to create, configure, start, and stop Tabsdata Instances, tdk allows users to interact with running Tabsdata Instances.

tdk -h                    # list all commands
tdk <command> -h          # help for a command group
tdk <command> <sub> -h    # help for a specific command

note

In a few places the help text refers to the tool as td; the command you run is always tdk.

The CLI Reference has the complete reference: every command, every flag, required vs. optional.

Interactive Explorer

Search or filter by command group, pick a command, then toggle on the flags you need. The command below fills in with placeholders for anything you haven't typed yet, ready to copy into your terminal.

113 commands

abouttdk about

Show build metadata and system information.

tdk about

This command takes no arguments or options.

Conventions

A few things apply across most commands.

Targeting a project. Most commands act inside a project. Store a default once with tdk set, or override it per command with --proj / -P:

tdk set --proj myproject             # default project for later commands
tdk collection list --proj other     # override for a single command

Targeting a collection. Commands that act on a collection take --coll / -c. A stored collection (within a stored project) lets you omit it:

tdk set --coll input

Output format. Read commands accept -o / --format with table (the default), json, or yaml.

Confirming destructive commands. Every delete asks you to type delete to confirm. Pass --confirm delete to skip the prompt.

Global options. --version, -h / --help, and --no-prompt (never prompts; it fails if input would be required, which is useful in scripts).

---

Sessions

Connect to a server and manage your session.

• tdk login: log in to a server. You are prompted for anything you omit.

  tdk login --server localhost --user admin --password tabsdata

• tdk logout: end the session and clear cached credentials.
• tdk status: check that the server is up.
• tdk auth info: show the currently authenticated user.
• tdk auth password-change SERVER_URL: change a password (--user, --old-password, --new-password).
• tdk auth add-cert / delete-cert: manage a self-signed server certificate (--server, --pem).

Projects

tdk project manages projects. These commands do not take --proj. The --name is the target.

• create: tdk project create --name myproject [--description D]
• list: tdk project list
• info: tdk project info --name myproject
• update: tdk project update --name myproject [--new-name N] [--description D]
• delete: tdk project delete --name myproject --confirm delete

Groups

tdk group manages the groups inside a project: the built-in sources / destinations, and your own (for example, medallion bronze / silver / gold). All take --proj (or use a pin).

• create: tdk group create --name bronze [--description D]
• list / info / update / delete: as for projects. System groups can't be updated or deleted.

Users and access

tdk user manages accounts; tdk permission grants access. See Permissions for the full model.

Users:

• create: tdk user create --name alice --email alice@corp.com [--full-name F] [--disabled]
• list / info / update / delete: standard.

Permissions:

• grant: tdk permission grant --user alice --permission develop_project --proj myproject
• revoke: same shape as grant.
• list: a user's permissions, or who can reach a project:

  tdk permission list --user alice
  tdk permission list --proj myproject

Permission values: view_project, develop_project, manage_project (project-scoped, require --proj); create_projects, manage_system (system-scoped, no --proj).

Settings

tdk set stores values in options.json under the Tabsdata directory (~/.tabsdata), where they apply to every later invocation. More than one can be set at once.

• set: tdk set --proj myproject [--coll input], and --server, --hints, --prompt
• show: tdk settings
• unset: tdk unset --proj (the project and its collection), --coll (the collection only), or --all (every setting).

Collections and connections

tdk collection manages collections; tdk connection helps you build and check connection files offline. See Connections for the full workflow.

Collections (all take --proj or a pin):

• create: a source or destination collection must pass --conn-file, and its group must match the connection type. A plain collection defaults to the default group.

  tdk collection create --name input --group sources --conn-file conn-input.yaml
  tdk collection create --name dataprod --group default

• list / info: standard, with -o.
• connection: tdk collection connection --name input shows a source/destination collection's connection (never the secret values).
• update: change name, description, or base path, or replace the connection with --conn-file.
• delete: --confirm delete.

Connections are built offline (no server needed). A connection is a small YAML document that names the external system a source/destination collection talks to, and how to authenticate.

• types: list the available types: tdk connection types. A type name reads <system>-<access>-<direction>: for example mysql-sql-in (MySQL source), s3-file-out (S3 destination), postgres-cdc (PostgreSQL stream source).
• template: write a fill-in template for a type: tdk connection template --type mysql-sql-in --file conn.yaml.
• validate: check a document: tdk connection validate --file conn.yaml.

A filled-in MySQL source connection looks like this:

kind: connectionDef
apiVersion: '1.0'
type: tabsdatak.conn.mysql:MySQLSrcConn
spec:
  uri: 'mysql://db.internal:3306/sales'
  credentials:
    kind: userPasswordCredentials
    apiVersion: '1.0'
    type: tabsdatak.conn.common.types:UserPassword
    spec:
      user: '$secret:MYSQL_USER'
      password: '$secret:MYSQL_PASSWORD'

Secret values take a secret:<value> prefix, or $secret:<ENV_VAR> to read the value from an environment variable when the collection is created, so no secret is ever written into the stored document. Once the file is ready, pass it to tdk collection create --conn-file (shown above).

Functions

tdk fn registers and runs your publishers, transformers, and subscribers. All take --coll (and --proj, or use pins).

• register: add a function from a file. --path is FILE.py::function_name.

  tdk fn register --coll input --path flow.py::my_publisher

  Useful flags: --update (register or update idempotently), --enabled / --disabled, --reuse-tables, --requirements FILE, --local-pkg PKG, --base-path.
• trigger: run a function and its downstream plan. --plan-name names the run; --detach returns without monitoring.

  tdk fn trigger --coll input --name my_publisher

• update: re-register an existing function from --path (also --reset-state, --reset-stage).
• enable / disable: turn a function on or off (--name, --coll).
• info: tdk fn info --name my_publisher --coll input [--show-history].
• list: tdk fn list --coll input.
• delete: --confirm delete.
• patch / list-patches: register a code-only patch of a specific function version (--patch-of FVID) and list patches. Advanced; see -h.

Tables

tdk table inspects and exports the tables your functions produce (--coll, --proj or pins). Most read commands accept a point in time: --at (a timestamp), --at-trx (end of a transaction), or --version (a specific data version).

• list: tdk table list --coll dataprod [--name "sales*"]
• schema: tdk table schema --name sales --coll dataprod
• versions: tdk table versions --name sales --coll dataprod [--details]
• data: preview rows: tdk table data --name sales --coll dataprod [--len 20]
• download: save as Parquet: tdk table download --name sales --coll dataprod --file s.parquet
• delete: --confirm delete.

Execution

A plan is one execution (the graph of functions); a plan is made of transactions (one per collection); each function runs as a function run, carried out by workers. tdk plan, tdk trx, tdk fnrun, and tdk worker each manage one of these.

Plans (tdk plan):

• list: tdk plan list [--status R] [--coll C] [--fn F] [--name "my_plan*"] [--last] [--monitor]
• get: tdk plan get --plan PLAN shows a plan, its function runs, and its workers.
• monitor: tdk plan monitor --plan PLAN follows it until it finishes.
• cancel / recover: tdk plan cancel --plan PLAN --confirm cancel, tdk plan recover --plan PLAN.
• logs: tdk plan logs --plan PLAN [--file -].

Transactions (tdk trx): the same shape as plans, filtered by --trx instead of --plan.

Function runs (tdk fnrun):

• list: tdk fnrun list [--status R] [--coll C] [--fn F] [--plan P] [--trx T]
• get: tdk fnrun get --fnrun FNRUN
• logs: tdk fnrun logs --fnrun FNRUN [--file -]
• recover: tdk fnrun recover --fnrun FNRUN
• replay: re-run a finished function run: tdk fnrun replay --fnrun FNRUN.

Workers (tdk worker):

• list: tdk worker list [--status R] [--coll C] [--fn F] [--plan P] [--trx T] [--fnrun FR]
• logs: tdk worker logs --worker WID [--file -]
• recover: tdk worker recover --worker WID

Status filters accept short codes (R running, D done, E error, F failed/finished, C committed, and more). See each command's -h for the full list.

Metrics

tdk metrics summarizes operational activity (--proj or pins).

• show: a summary over a time window, per collection or group:

  tdk metrics show --dim collection --unit day --span 7

  Filters: --collection, --group, --status (comma-separated), --collection-exclude, --group-exclude.
• inflight: a point-in-time view of work still running, per collection / group / status.

Examples and extras

• tdk examples list: list the bundled examples.
• tdk examples extract --name quickstart-dev --dir qs-example: copy an example into a new directory (which must not exist yet).
• tdk shell: start an interactive tdk shell.
• tdk set --hints true|false: toggle the hints the CLI adds to errors.
• tdk about: build and system information.
• tdk info license, tdk info third-party, tdk info release-notes: license text, third-party dependencies, and the release notes for the installed version.