Custom Tables

The hutly tables command group manages custom tables in your Hutly organization — both the table schemas (defined in YAML and created from disk) and the rows stored inside them.

Table schemas are immutable. Once a table exists, you cannot add, remove, or retype a column in place. To change the shape of a table you must delete it and recreate it from an updated YAML file, which destroys all existing rows. Rows, by contrast, are fully mutable: create, update, delete, and bulk-import them with hutly tables rows.

All commands operate against the organization configured in your CLI context and require valid credentials. Every command accepts --json; JSON is the default machine-readable output for read commands, and the flag is a no-op elsewhere for scripting compatibility.

Schema commands

hutly tables list

List the custom tables in the current organization.

hutly tables list
hutly tables list --limit 50 --offset 50 --pretty

hutly tables get

Fetch a table’s schema plus its first page of rows (up to 100) as a single bundle.

hutly tables get applicants
hutly tables get applicants --pretty

hutly tables describe

Fetch a table’s schema only, with no rows. Use get when you also want the first page of rows.

hutly tables describe applicants --pretty

hutly tables push

Create a custom table from a YAML file. Table names must contain only letters, numbers, and underscores.

Because schemas are immutable, push refuses to overwrite a table that already exists. Pass --force-recreate to drop the existing table — this deletes all of its rows — and recreate it from the YAML. The CLI prompts for confirmation before any destructive recreate; --yes skips the prompt.

hutly tables push tables/applicants.yaml
hutly tables push tables/applicants.yaml --force-recreate
hutly tables push tables/applicants.yaml --force-recreate --yes
hutly tables push tables/applicants.yaml --var region=vic

Table schema YAML

A table YAML document has a name, an optional description, and a non-empty fields array. Each field is either a plain column or a Data Dictionary–linked column.

name: applicants
description: Rental applicants captured during screening
fields:
  - name: full_name
    type: text
    required: true
    comments: Applicant's full legal name
  - name: monthly_income
    type: numeric
    required: false
    comments: Stated gross monthly income
  - name: screened
    type: boolean
    required: false
    default: false
    comments: Whether the applicant has been screened

Plain-column fields:

Data Dictionary columns use the ddField shorthand, linking a column to a live Hutly Data Dictionary field by its canonical forms_fields.name. The server resolves and freezes the DD snapshot (label, type, enum values) at create time, so later DD edits don’t silently break the table.

name: lease_parties
fields:
  - ddField: tenant_full_name
    required: true
  - ddField: lease_start_date
    required: false

hutly tables pull

Fetch a table’s schema and write it to a YAML file. Rows are not included — manage those with hutly tables rows. DD-linked columns round-trip as the ddField shorthand so a pulled file can be pushed back without invalidating the link.

hutly tables pull applicants
hutly tables pull applicants --output ./schemas/applicants.yaml

hutly tables delete

Permanently delete a custom table and all of its rows. This is irreversible. The CLI prompts for confirmation; pass --yes to skip it.

hutly tables delete applicants
hutly tables delete applicants --yes

Row commands

Rows live under hutly tables rows <verb> <tableName>.

hutly tables rows list

List rows in a table. Pass --filter and --order multiple times to build compound queries.

hutly tables rows list applicants
hutly tables rows list applicants --limit 50 --offset 0 --pretty
hutly tables rows list applicants \
  --filter "monthly_income:gte:5000:and" \
  --filter "screened:eq:true:and" \
  --order "monthly_income:desc"

Filter segments take the form field:op:value:join:

• op is one of eq, ne, gt, lt, gte, lte, like, ilike, in, nin
• join is and or or, combining the segment with the next one

Order segments take the form field:asc or field:desc; repeat for multi-key ordering.

hutly tables rows create

Insert a single row. Provide the column values as a JSON object that matches the table’s field schema, either inline or from a file.

hutly tables rows create applicants --data '{"full_name":"Sam Lee","monthly_income":6200,"screened":false}'
hutly tables rows create applicants --data-file ./row.json

Pass exactly one of --data or --data-file.

hutly tables rows update

Replace the columns of a single row, identified by its numeric id (a positive integer).

hutly tables rows update applicants 42 --data '{"screened":true}'
hutly tables rows update applicants 42 --data-file ./update.json

Pass exactly one of --data or --data-file.

hutly tables rows delete

Delete a single row by its numeric id. The CLI prompts for confirmation; pass --yes to skip it.

hutly tables rows delete applicants 42
hutly tables rows delete applicants 42 --yes

hutly tables rows import

Bulk-insert rows from a JSON file. The file must contain a JSON array of row objects. The server validates each row independently and reports per-row errors; partial success is allowed. When any rows fail, the command prints the result envelope and exits non-zero.

hutly tables rows import applicants ./applicants-seed.json

[
  { "full_name": "Sam Lee", "monthly_income": 6200, "screened": false },
  { "full_name": "Jo Park", "monthly_income": 4800, "screened": true }
]