Skip to main content

AutessaDB

AutessaDB is the platform's system of record, and the autessadb namespace is the largest in the CLI. Tables, rows, security roles, triggers and the audit trail are all reachable from the terminal, and every read and write goes through the same row-level and field-level security the web app enforces.

Key concepts​

The sub-namespaces​

NamespaceWhat it does
autessadb tablesCreate and administer tables — schema, security, sharing, ownership, soft-delete
autessadb queryRead and write rows, including bulk operations and semantic search
autessadb triggerPer-row automation that fires on insert, update or delete
autessadb rolesThe security roles that scope access
autessadb access-logThe row-level data access audit trail
autessadb driveFiles and folders in a Drive: browse, push and pull folders, grep, search, read, and share
autessadb analyticsAnalytics tables: load files and run read-only SQL

Typed column values​

This is the one thing that trips people up. Rows are not flat maps of column name to scalar. Each value is an AutessaDbColumnValue object carrying a columnType and the matching typed field:

{
"task": { "columnType": "SHORT_TEXT", "textValue": "Write the CLI docs" },
"status": { "columnType": "SINGLE_SELECT", "textValue": "doing" },
"id": { "columnType": "INTEGER", "integerValue": 1 }
}

Sending a bare value gets you a clear error rather than a silent misparse:

error [ENDPOINT_ERROR]: The request body did not match this endpoint's schema. Field $.values.
expected an object but got a string — send an object of that field's type
(e.g. { "columnType": ..., "...Value": ... }), not a bare value.

The reliable way to learn a column's typed field name is to read one row back with query get-data and copy the shape.

Filters are the exception. whereGroups conditions take plain scalars in value — the typed-object form is only for writing rows and reading them back.

Built-in columns​

Every table gets id, created_at and updated_at automatically. Do not declare them in a schema, and omit them when inserting — they are set for you. They are valid in filters and sort terms.

How to create a table​

autessa autessadb tables create \
--tableName docs_cli_scratch \
--schema '{
"columnDefinitions": [
{
"columnName": "task",
"columnType": "SHORT_TEXT",
"required": true,
"columnComment": "What needs doing."
},
{
"columnName": "status",
"columnType": "SINGLE_SELECT",
"allowedValues": ["todo", "doing", "done"]
}
]
}'
{ "tableId": "ayXduiaLeFKh" }

Columns live in schema.columnDefinitions — not a field called columns. Per-column options worth knowing:

FieldEffect
requiredEvery row must carry a value
columnCommentA human- and model-facing description of what the column holds
allowedValuesThe option set for SINGLE_SELECT / MULTI_SELECT
vectorizeFieldIndex the column for semantic search (SHORT_TEXT, LONG_TEXT, FILE, AUDIO only)
maskedStore encrypted at rest (SHORT_TEXT / LONG_TEXT only)

Two schema-level flags matter at create time:

  • appendOnly makes the table write-once — rows can be inserted and read but never updated or deleted. It is a one-way latch: it can be turned on later but never off, so set it at creation for ledger and audit tables. Computed columns are not allowed on one, and column removal is rejected because it would destroy history.
  • tags are free-form organizational labels.
DATETIME is legacy and rejected on create. Use SHORT_TEXT holding a UTC ISO-8601 string instead.

Read a table's full configuration back with autessa autessadb tables get --tableId <id>, and list what you can reach with tables all — which splits results by how you got access: owned, shared company-wide, shared directly with you.

How to write rows​

One row​

autessa autessadb query insert --tableId ayXduiaLeFKh --values '{
"task": { "columnType": "SHORT_TEXT", "textValue": "Write the CLI docs" },
"status": { "columnType": "SINGLE_SELECT", "textValue": "doing" }
}'
{
"insertedId": 1,
"newRow": {
"id": { "columnType": "INTEGER", "integerValue": 1 },
"task": { "columnType": "SHORT_TEXT", "textValue": "Write the CLI docs" },
"status": { "columnType": "SINGLE_SELECT", "textValue": "doing" },
"created_at": { "columnType": "SHORT_TEXT", "textValue": "2026-09-10 09:26:50.497812" },
"updated_at": { "columnType": "SHORT_TEXT", "textValue": "2026-09-10 09:26:50.497812" }
}
}

Required columns and select-option membership are validated, and writing a column your field-level security forbids is rejected. Insert triggers and computed columns fire asynchronously afterwards — a computationStatus of COMPUTING in the response means computed columns are still being calculated.

Updating​

autessa autessadb query update --tableId ayXduiaLeFKh --rowId 1 --values '{
"status": { "columnType": "SINGLE_SELECT", "textValue": "done" }
}'

Only the columns you send change. Omitted columns keep their current values, which is what lets a script update one field safely while a person edits another in the UI.

Many rows at once​

CommandUse
query bulk-insertInsert many rows in one call
query bulk-update-by-idsUpdate many rows by numeric id
query bulk-delete-by-idsDelete many rows by numeric id
query batch-updateUpdate every row matching a filter
query batch-deleteDelete every row matching a filter

The bulk-* family addresses rows by id; the batch-* family addresses them by whereGroups. Prefer either over a loop of single-row calls — they are one round trip and one unit of work.

How to query rows​

Everything, paged​

autessa autessadb query get-data --tableId ayXduiaLeFKh --output table

Returns the schema plus a page of rows, sorted newest-updated first.

Filtered​

whereGroups is an array of groups; conditions inside a group combine with the group's logicalOperator, and the groups themselves combine with --groupsLogicalOperator:

autessa autessadb query query --tableId ayXduiaLeFKh --whereGroups '[
{
"logicalOperator": "AND",
"conditions": [
{ "columnName": "status", "operator": "EQUALS", "value": "doing" },
{ "columnName": "created_at", "operator": "GREATER_THAN", "value": "2026-09-01" }
]
}
]'
{
"rows": [
{
"id": 1,
"columnData": {
"task": { "columnType": "SHORT_TEXT", "textValue": "Write the CLI docs" },
"status": { "columnType": "SINGLE_SELECT", "textValue": "doing" }
},
"createdAt": "2026-09-10T09:26:50.497812",
"updatedAt": "2026-09-10T09:26:50.497812"
}
]
}

Available operators: EQUALS, NOT_EQUALS, GREATER_THAN, LESS_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN_OR_EQUAL, CONTAINS, ICONTAINS, STARTS_WITH, ENDS_WITH, LIKE, ILIKE, IN, NOT_IN, BETWEEN, IS_NULL, IS_NOT_NULL. Omitting operator defaults to EQUALS.

A few rules that save debugging time:

  • IN / NOT_IN take an array; BETWEEN takes exactly two values [low, high]; IS_NULL / IS_NOT_NULL ignore value.
  • ICONTAINS is the right operator for a user-typed search box — it is case-insensitive CONTAINS.
  • LIKE and ILIKE pass % and _ through unescaped. Never hand them raw user input.
  • Media columns support only IS_NULL / IS_NOT_NULL. Masked columns support equality operators only.

Sorting and paging:

autessa autessadb query query --tableId ayXduiaLeFKh \
--orderBy '[{"columnName":"created_at","direction":"ASC"}]' \
--page 1 --pageSize 25

orderBy defaults to updated_at DESC then id DESC. Direction defaults to DESC — only an explicit ASC ascends. Page numbers here are 1-based, unlike the 0-based paging used by the history commands.

# follow foreign keys
autessa autessadb query join-query --tableId ayXduiaLeFKh --json '{...}'

# group-by rollups computed server-side
autessa autessadb query aggregate --tableId ayXduiaLeFKh --json '{...}'

# vector search over a vectorized column
autessa autessadb query semantic-search --tableId ayXduiaLeFKh --json '{...}'

semantic-search needs a column created with vectorizeField: true. Run each command's help for its exact argument shape.

How to change a schema​

autessa autessadb tables update-schema --tableId ayXduiaLeFKh --json '{...}'

update-schema adds columns, removes columns, and adds options to SINGLE_SELECT / MULTI_SELECT columns. There is no rename and no retype — changing a column's name or type means adding a new one and migrating.

This is a replace-semantics method, so --replace applies if you are sending an authoritative schema rather than a delta. See Global flags.

How to add a trigger​

Triggers fire per row on insert, update or delete, and run a tool, an agent, a manager, or a write to another table:

autessa autessadb trigger add --tableId ayXduiaLeFKh --json '{...}'
autessa autessadb trigger all --tableId ayXduiaLeFKh
autessa autessadb trigger disable --tableId ayXduiaLeFKh --triggerId <id>
autessa autessadb trigger enable --tableId ayXduiaLeFKh --triggerId <id>

disable stops a trigger firing without deleting it — the right move when you are debugging a loop, since delete is permanent.

Read what fired, with decrypted event input and response output:

autessa autessadb trigger history --tableId ayXduiaLeFKh --year 2026 --month 9
autessa trigger-history list --tableId ayXduiaLeFKh
autessa trigger-history detail --eventId a02e8438-9032-46f3-a875-41d051f2c013

autessadb trigger history is per-table and per-month; the top-level trigger-history namespace lists across the whole company newest-first, with detail returning full uncapped payloads. Both back the same views described in Triggers.

How to review access​

autessa autessadb access-log list --tableId ayXduiaLeFKh

The row-level data access log, newest first, filterable by table, row, date range and action. This is the record of who read and wrote which rows — the audit surface the web app renders, readable from the terminal.

How to manage security​

autessa autessadb roles list
autessa autessadb roles create --json '{...}'
autessa autessadb tables update-settings --tableId ayXduiaLeFKh --json '{"rlsEnforced":true}'
autessa autessadb tables share --tableId ayXduiaLeFKh --level COMPANY --accessLevel READ

update-settings is owner-or-ADMIN only. It toggles row-level security enforcement and sets the default role auto-assigned to grantees when the table is shared. get-sharing-details shows exactly what share and update-settings would modify, without changing anything.

How to delete and restore​

autessa autessadb tables cli-delete --tableId ayXduiaLeFKh
autessa autessadb tables list-deleted
autessa autessadb tables restore --tableId ayXduiaLeFKh

Table deletion is a soft delete with a 14-day grace period. list-deleted is your trash, showing the time left before each table is purged, and restore brings one back within that window.

Shorthand: autessa drive​

Short commands for Drives (CLI 0.6.0 and later). Pick the Drive once with autessa drive use <name>; it is remembered for the profile. Paths are relative to the Drive root (a leading / is optional; / alone is the whole Drive). Output is plain text; add --json for the raw response, or --drive <name> to use another Drive for one command.

CommandWhat it does
autessa drive use [name]Pick the Drive (by name or ID); without a name, list your Drives
autessa drive ls [path]List a folder
autessa drive tree [path]Show the folder structure
autessa drive stat <path>Size, version, text status and your access
autessa drive cat <path>Print a file's text (--numbers keeps line numbers; --pages 2-3 or --lines 1-50 for a range)
autessa drive read <path> --pages 3-5Print one range of a file's text
autessa drive grep <text> [folder]Find exact text: one path:page:line: text line per match
autessa drive search "<words>" [folder]Ranked keyword search; meaning-based when semantic search is enabled
autessa drive touch <path>Create an empty file (no change if it exists)
autessa drive write <path> [text]Create or replace a text file; text from the argument or stdin
autessa drive append <path> [text]Add text to the end of a file; text from the argument or stdin
autessa drive edit <path> --old <text> --new <text> [--all]Replace exact text
autessa drive mkdir <path>...Create folders
autessa drive mv <from> <to>Move into a folder, or rename by giving a new path (--confirm when access changes)
autessa drive rm <path>... [--forever]Move to the trash, or delete for good
autessa drive comment <path> "text" [--page N] [--reply <threadId>]Add a comment, optionally on a page or as a reply
autessa drive comments <path> [--includeResolved]List a file's comment threads
autessa drive share <path> --team <name> | --user <email> | --company | --members --role viewer|commenter|editorShare a file or folder (--members: with every Drive member), or / to add Drive members
autessa drive link <path>Create a view link (--audience ANYONE for a public one)
autessa drive open <path>Print a 10-minute download link
autessa drive push <local folder> [drive folder]Upload a local folder (resumable)
autessa drive pull <drive folder> <local folder>Download a Drive folder
autessa drive use Docs
echo "- Acme prefers Net 45" | autessa drive append notes/memory.md
autessa drive edit notes/memory.md --old "Net 45" --new "Net 60"
autessa drive grep "Net 60" notes/

Errors show the server's code and a hint, for example error [EDIT_AMBIGUOUS]: oldText matches 2 places followed by hint: Add surrounding words…. Run autessa drive help <command> for a command's arguments and the full command it runs.

Shorthand: autessa analytics​

CommandWhat it does
autessa analytics use [table]Pick the analytics table; without a name, list them
autessa analytics describeColumns, partition columns and size
autessa analytics load <file> [--mode REPLACE]Upload a CSV, Parquet or JSON-lines file and load it
autessa analytics query "<sql>"Run SQL and print the rows (waits for the job; Ctrl-C cancels)
autessa analytics jobsRecent query and load jobs
autessa analytics suggest [--focus measures] [--apply]Draft the semantic layer with AI; --apply saves it

--table <name> uses another table for one command.

How to work with a Drive​

A Drive is a table of files and folders, and autessadb drive treats it like a remote file system. Every command takes the Drive's --tableId, and paths are absolute (/Shared/Legal/Contracts). Commands run as you, so you see and change exactly what you could in the explorer.

Browse​

autessa autessadb drive ls --tableId V1StGXR8Z5 --path /Shared/Legal --output table
autessa autessadb drive tree --tableId V1StGXR8Z5 --path /Shared/Legal --maxDepth 2
autessa autessadb drive find --tableId V1StGXR8Z5 --path /Shared --glob '*.pdf' --modifiedAfter 2026-09-01T00:00:00Z
autessa autessadb drive stat --tableId V1StGXR8Z5 --path /Shared/Legal/Contracts/acme-msa.pdf
id type name sizeBytes version extractionStatus
---- ------ ------------- --------- ------- ----------------
4190 FOLDER Archive
4182 FILE acme-msa.pdf 482113 2 EXTRACTED

Listings are paged. When a response carries a nextCursor, pass it back as --cursor with the same other flags. truncated tells you whether a response is complete; nothing is dropped silently.

Upload a folder​

autessa autessadb drive push --tableId V1StGXR8Z5 --localDir ./contracts --path /Shared/Legal/Contracts
scanning ./contracts ... 214 files, 1.8 GB
uploading [=============> ] 131/214 1.1 GB 4 parallel
committed 214 files, created 9 folders

push walks the local folder, creates the matching folders, uploads files four at a time (large files in parts), and commits them. Progress goes to stderr, so stdout stays clean JSON. Add a .autessaignore file (same syntax as .gitignore) to the local folder to skip files.

FlagEffect
--onConflict FAIL|RENAME|NEW_VERSIONWhat to do when a file already exists. FAIL (default) skips and reports that file; RENAME keeps both; NEW_VERSION replaces it and keeps the old content as a version.
--mirrorAlso move Drive files that are no longer in the local folder to the trash. Without it, push only adds and updates.

To upload a single file:

autessa autessadb drive upload --tableId V1StGXR8Z5 --localFile ./initech-msa.pdf --path /Shared/Legal/Contracts/initech-msa.pdf

Download a folder​

autessa autessadb drive pull --tableId V1StGXR8Z5 --path /Shared/Legal/Contracts --localDir ./contracts

pull recreates the folder structure locally and verifies each file's checksum after download.

Search and read​

# exact text, one line per match
autessa autessadb drive grep --tableId V1StGXR8Z5 --path /Shared/Legal \
--pattern 'termination for convenience' --caseInsensitive true --output text

# ranked search (meaning-based when the Drive's semantic search is on)
autessa autessadb drive search --tableId V1StGXR8Z5 --query 'terminate contract early'

# read a page or a line range
autessa autessadb drive read --tableId V1StGXR8Z5 --path /Shared/Legal/Contracts/acme-msa.pdf --pages 4
/Shared/Legal/Contracts/acme-msa.pdf:4:12: 12.2 Termination for Convenience. Either party may terminate this Agreement
/Shared/Legal/Contracts/globex-msa.pdf:7:3: 9.1 Termination for Convenience. Customer may terminate upon thirty (30) days

--output text prints path:page:line: text, ready for grep, sort, or an editor's quickfix list. For text files the page is omitted and the line is the file's real line number. Add --regex true for regular expressions and --context 2 for surrounding lines.

Organize and share​

autessa autessadb drive mkdir --tableId V1StGXR8Z5 --path /Shared/Legal/Contracts/2026
autessa autessadb drive move --tableId V1StGXR8Z5 --path /Drafts/sow.docx --destination /Shared/Legal/Contracts
autessa autessadb drive trash --tableId V1StGXR8Z5 --path /Shared/Legal/Contracts/old
autessa autessadb drive shares upsert --tableId V1StGXR8Z5 --path /Shared/Legal \
--principals '[{"type":"TEAM","teamId":"3b1f6a2e-7c41-4d55-9a0e-58c2b7f1d903"}]' --role VIEWER
autessa autessadb drive shares list --tableId V1StGXR8Z5 --path /Shared/Legal/Contracts/acme-msa.pdf

To add Drive members, use --path / (or the shorthand autessa drive share / --team Finance --role editor). Members see the Drive but no folder or file in it until that item is shared with them; autessa drive share Legal --members --role viewer shares a folder with every current member. A move that would change who has access returns requiresConfirmation with the list of who would gain or lose access, and moves nothing. Re-run with --confirm true to go ahead.

How to load and query analytics tables​

Analytics tables are queried with read-only ANSI SQL. Loads and queries run as asynchronous jobs, and queries typically take a few seconds; by default the CLI waits for the job and prints the result.

Load a file​

autessa autessadb analytics load --tableId V1StGXR8Z5 --localFile ./orders-2026-09.parquet
autessa autessadb analytics load --tableId V1StGXR8Z5 --localFile ./orders.csv --mode REPLACE

load uploads the local CSV or Parquet file in parts, starts the load, and waits for it to finish, printing rows loaded and any rejected rows. --mode is APPEND (default) or REPLACE.

Run a query​

autessa autessadb analytics query --tableId V1StGXR8Z5 --output table --sql "
SELECT region, SUM(net_amount) AS revenue
FROM order_lines
WHERE order_date >= DATE '2026-01-01'
GROUP BY region
ORDER BY revenue DESC"
region revenue
------ -----------
NA 28411093.20
EMEA 15002118.45
APAC 6120774.00
FlagEffect
--output table|csv|jsontable for reading, csv to save or pipe (> revenue.csv), json (default) for scripts.
--maxRowsCap the rows kept in the result.
--no-waitReturn the jobId immediately instead of waiting.

With --no-wait, check on the job and fetch its result later:

autessa autessadb analytics query --tableId V1StGXR8Z5 --sql "SELECT ..." --no-wait
autessa autessadb analytics job-status --tableId V1StGXR8Z5 --jobId 1f8e5c3a-9b2d-4e7f-a6c1-3d0b9e2f7a54
autessa autessadb analytics job-results --tableId V1StGXR8Z5 --jobId 1f8e5c3a-9b2d-4e7f-a6c1-3d0b9e2f7a54 --output csv
autessa autessadb analytics cancel --tableId V1StGXR8Z5 --jobId 1f8e5c3a-9b2d-4e7f-a6c1-3d0b9e2f7a54

Draft the semantic layer with AI​

autessa analytics suggest # print the AI draft (JSON)
autessa analytics suggest --focus measures # only measures
autessa analytics suggest --apply # print, then save it

--apply saves through update-semantics at the version the draft was made from, so a concurrent edit is refused rather than overwritten. Needs CLI 0.7.0 or later.

Describe before you query​

autessa autessadb analytics describe --tableId V1StGXR8Z5
autessa autessadb analytics estimate --tableId V1StGXR8Z5 --sql "SELECT COUNT(*) FROM order_lines"

describe returns the SQL name, columns, partition columns, measures, joins, and verified queries. estimate reports how much data a query would scan without running it. Filter on partition columns to keep scans small.

drive push, drive pull, drive upload, and analytics load read and write local files, which needs a recent CLI. If the command is missing, update with npm install -g @autessa/cli and run autessa --refresh help.

Full command reference​

39 commands39 runnable
CommandWhat it does
autessa autessadb access-log listList the company's row-level data access log, newest first, filterable by table, row, date range, and action.
autessa autessadb query aggregateRun a group-by aggregation over a table — count/sum/avg/min/max and similar rollups computed server-side.
autessa autessadb query batch-deleteDelete every row matching the given WHERE groups in one call.
autessa autessadb query batch-updateUpdate every row matching the given WHERE groups to the given column values in one call.
autessa autessadb query bulk-delete-by-idsDelete many rows by their numeric ids in one call.
autessa autessadb query bulk-insertInsert many rows in one call.
autessa autessadb query bulk-update-by-idsUpdate many rows by their numeric ids in one call.
autessa autessadb query delete-rowDelete a single row by its numeric row id.
autessa autessadb query generate-upload-linkGet a presigned S3 PUT URL to upload media for a FILE/IMAGE/AUDIO/VIDEO column.
autessa autessadb query get-dataPage through all of a table's rows with no filters, sorted newest-updated first (updated_at DESC, id DESC).
autessa autessadb query get-single-rowFetch one row by its numeric row id.
autessa autessadb query insertInsert one row into a table as a map of column name to typed value.
autessa autessadb query join-queryQuery a table joined to related tables via foreign keys, with WHERE groups, ordering, column projection, and pagination.
autessa autessadb query queryQuery a table's rows with WHERE groups, ordering, and pagination — the primary way to read filtered data.
autessa autessadb query semantic-searchSemantic (vector) search over a table's indexed column, ranked by similarity to a query string.
autessa autessadb query updateUpdate a single row's column values by row id; only the columns you send change (omitted columns keep their current value, so this coexists with concurrent user edits to other columns).
autessa autessadb roles createCreate an AutessaDB security role.
autessa autessadb roles deleteDelete an AutessaDB security role and its assignments.
autessa autessadb roles getFetch one AutessaDB security role by roleId, including its table policies and assignments.
autessa autessadb roles listList the company's AutessaDB security roles.
autessa autessadb roles updateUpdate an AutessaDB security role.
autessa autessadb tables allList every AutessaDB table you can access in the current company, split by how you got access — tables you own, tables shared company-wide, and tables shared specifically with you.
autessa autessadb tables cli-deleteSoft-delete a table in one call.
autessa autessadb tables createCreate a new ordinary AutessaDB table.
autessa autessadb tables getFetch a table's full configuration (schema with columns, built-ins, triggers, settings, type, and tags) and your own access level on it, by table id.
autessa autessadb tables get-sharing-detailsGet a table's sharing level, company-wide permission, per-user grants, your own access level, and its row-security settings — a read-only view of exactly what share and update-settings would modify.
autessa autessadb tables list-deletedList your soft-deleted tables (your trash), each with the time left before it is permanently purged.
autessa autessadb tables restoreRestore a soft-deleted table within its 14-day grace period, before the hard-delete sweep purges it.
autessa autessadb tables shareSet a table's sharing mode — PRIVATE, COMPANY-wide at one access level, or SPECIFIC_MEMBER with per-user grants via usersToAdd/usersToRemove.
autessa autessadb tables update-schemaModify a table's schema by removing columns, adding columns, and adding SINGLE_SELECT/ MULTI_SELECT options (there is no rename or retype).
autessa autessadb tables update-settingsUpdate a table's security settings (owner or ADMIN only) — toggle rlsEnforced and set or clear the default role auto-assigned to grantees when the table is shared.
autessa autessadb trigger addAdd a trigger to a table that fires per row on INSERT/UPDATE/DELETE and runs a tool, an agent, a manager, or a write to another AutessaDB table.
autessa autessadb trigger allList all of a table's triggers (enabled or not).
autessa autessadb trigger deletePermanently remove a trigger from the table.
autessa autessadb trigger disableDisable a trigger without deleting it; it stops firing until re-enabled.
autessa autessadb trigger enableRe-enable a disabled trigger so it fires on future row changes.
autessa autessadb trigger getFetch a single trigger's configuration by id.
autessa autessadb trigger historyPage through a table's trigger execution history — which triggers fired, on what event, and their result — for a given year and month.
autessa autessadb trigger updateUpdate a trigger by submitting triggerId plus the complete modified trigger object.