Discovering Commands

The CLI has no manual to memorize because it generates its own. Command names, argument types, response fields and prose descriptions all come from the SDK manifest, and three help commands walk you from "I have no idea what exists" to "here is the exact flag I need".

What it's for

You will not find a printed list of every flag in these docs, and that is intentional — it would be stale within a release. Instead, learn the four moves on this page and the CLI will answer every "what can I do here" question itself.

The help tree

autessa help                          # every namespace, with a paragraph on each
autessa <namespace> help              # that namespace's commands, one line each
autessa <namespace> <command> help    # arguments, types, requiredness, and the response shape

Nesting works the same way at every depth:

autessa autessadb help
autessa autessadb query help
autessa autessadb query insert help

Namespace help

autessa tools help

Create, configure, run, and share tools — the capabilities you attach to agents. A tool is drafted
with create, configured (its type and arguments) with update, made runnable with publish, and can be
run directly with execute to test it. Creating and publishing a tool does NOT attach it to any agent
— attach it by adding it to an agent's tools array via the agents update command. [...]

*   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *
  COMMANDS in 'tools'
*   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *

  all                  List every tool you can access in the current company, split into three
                       buckets — tools you own, tools shared company-wide, and tools shared
                       specifically with you.

  create               Create a new bare draft tool with a name and description; set its type and
                       configuration afterward with update.
  [...]
  history:

    detail  Fetch one tool execution with its FULL (uncapped) decrypted request input and result
            output.

    list    List tool executions newest-first, scoped to your company, optionally filtered by tool
            and/or outcome, paginated.

Run 'autessa tools <command> help' for a command's arguments.

The namespace paragraph is worth reading rather than skimming — it carries the intended lifecycle ("draft with create, configure with update, publish to make runnable") and the traps ("publishing a tool does NOT attach it to an agent").

Command help

autessa tools create help

Create a new bare draft tool with a name and description; set its type and configuration afterward with update.

usage: autessa tools create [--flags]

*   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *
  ARGUMENTS
*   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *

  --toolName         (required) <string>     Display name; also the function name presented to the
                                             LLM.

  --toolDescription  (required) <string>     What the tool does; presented to the LLM to decide when
                                             to call it.

  Object/array args take JSON, e.g. --schema '{"columnDefinitions":[...]}'. Whole body: --json '{...}'.

*   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *
  RESPONSE
*   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *   *

  tool  <AutessaTool>  The newly created draft tool (no type/arguments set yet).
      toolId             <string>  Opaque id of the tool.
      name               <string>  Display name shown in the tool list; also the callable function
                                   name presented to the LLM.
      [...]

Nested object arguments expand inline, so you can see the shape of a --schema or --updatedTool without guessing.

Drill-down: running an incomplete command is safe

Invoking a command that still needs required arguments does not error and does not execute. It prints the argument list:

autessa tools create

This command needs arguments — add the flags below to run it.
[...the same help as above...]

So exploring is free. Type the command you think you want, read what it asks for, add the flags. Commands with no required arguments (autessa agents all) run straight away.

Passing arguments

Scalars

autessa tools publish --toolId gPdJwp5jbr9eN
autessa agents create --agentType SIMPLE --agentName "Digest bot"

--flag value and --flag=value both work. A flag with no following value is a bare true:

autessa app push --appId lCHdKACw4tpE --files '{}' --addOnly

Values are coerced to the type the manifest declares — integers, numbers and booleans are parsed rather than sent as strings.

Objects and arrays

Any argument the help shows as an object, an array, or a named type takes JSON:

autessa autessadb tables create \
  --tableName todos \
  --schema '{"columnDefinitions":[{"columnName":"task","columnType":"SHORT_TEXT","required":true}]}'

If you pass a bare string where an object is expected, the CLI says so before sending anything:

error: value for this argument must be JSON: doing

The whole body at once

--json replaces every other argument flag with one request body. This is the form to reach for when you are generating calls programmatically, or when a payload is long enough that shell quoting becomes the enemy:

autessa agents update --json '{
  "agentId": "K2UYSwk3Yy4i",
  "updatedAgent": {
    "agentId": "K2UYSwk3Yy4i",
    "agentType": "SIMPLE",
    "name": "Summarizer",
    "model": "SMALL_INSTRUCTION_FOLLOWING",
    "tools": [{ "toolId": "gPdJwp5jbr9eN" }]
  }
}'

From a file:

autessa agents update --json "$(cat agent.json)"

Global flags

These are handled by the CLI itself and are never passed through as SDK arguments.

Flag	Effect
--output json|table|csv|text	Response format. JSON is the default. csv writes the first array in the response as CSV; text is a line-oriented format for commands that define one, such as autessadb drive grep.
--no-wait	On commands that start a job (such as autessadb analytics query), return the job ID immediately instead of waiting for the result.
--json '{...}'	Send this object as the entire request body.
--profile <name>	Run against a specific saved sign-in.
--refresh	Re-fetch the SDK manifest before running.
--full	On list commands that support a summary argument, return full records instead of trimmed ones.
--replace	Skip the SDK's read-merge-write on replace-semantics methods — send the value as authoritative.

--output table

autessa agents all --output table

agentId       agentType  name                 model                        maxIterations
------------  ---------  -------------------  ---------------------------  -------------
4fyAZFoKALmC  SIMPLE     HiOnceEmailAgent     SMALL_INSTRUCTION_FOLLOWING  1
vI9tkBVAtMce  SIMPLE     Hi Emailer           BIG_INSTRUCTION_FOLLOWING    30
bMR35XZD37Ol  SIMPLE     Message Digest       BIG_INSTRUCTION_FOLLOWING    6

Table mode finds the first array in the response and flattens it, dropping nested-object columns. It is a reading convenience — when a response has no array, or has nested structure that matters, it falls back to JSON. Never parse table output in a script; parse the JSON.

--full

List commands that accept a summary argument default to the trimmed form, so a company with hundreds of agents still returns a response under the size limit. --full opts out:

autessa tools all           # trimmed records
autessa tools all --full    # complete records

An explicit --summary true|false always wins over --full.

--replace

Several update methods read the current value, merge your changes into it, and write the result — so omitting a field leaves it alone. --replace skips the merge and treats what you send as the complete new value. Use it when you are pushing an authoritative snapshot (a full schema, a full file set) and want fields you omitted to actually disappear.

Reading the output

Successful commands print JSON to stdout; errors go to stderr. That split is what makes the CLI composable:

autessa agents all | jq -r '.ownedAgents[].agentId'
autessa tools history list --status error 2>/dev/null | jq '.executions | length'

A useful pattern for scripts — capture an id from a create:

TOOL_ID=$(autessa tools create \
  --toolName summarize \
  --toolDescription "Summarize text in one sentence." \
  | jq -r '.tool.toolId')

Exit codes

Code	Meaning
0	Command ran and succeeded
1	Anything that failed: unknown command, validation error, application error, expired session
2	You named a namespace instead of a command — its help was printed

Exit code 2 is the one to special-case in scripts: it means "you stopped one level short", not "something broke".

Errors

Validation errors

Missing or malformed arguments come back with the SDK's own field table, not a generic message:

autessa agents create --agentName "Digest bot"

error [SDK_VALIDATION_ERROR]: Missing required field(s): agentType

Request fields:
| Field | Type | Required | Description |
|---|---|---|---|
| agentType | one of: SIMPLE | yes | The kind of agent to create. The SDK only creates SIMPLE agents; must be SIMPLE. |
| agentName | string | yes | Display name shown in the agent list. |
| agentDescription | string | - | Human-facing description of what the agent does. |

Type errors

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 error names the JSON path, so $.values. points at the exact argument to fix.

Stale command list

error [SDK_UNKNOWN_ENDPOINT]: No SDK endpoint named 'agenticManagers.all'
note: your cached command list was out of date — refreshed it. Re-run the command
(a name may have changed, e.g. agenticManagers → managers; 'autessa help' shows the current ones).

This almost never means the command is gone. Your cached manifest predates a rename or addition. The CLI has already refreshed by the time you read the message — re-run, and use autessa <namespace> help if the name did change.

Expired session

error: Session expired. Run 'autessa login' to sign in again.

There is no silent refresh by design. Run autessa login (with --profile if you are not on the default).

Unknown command

error: Unknown command 'agents runit'. Try 'autessa help'.

Walk the help tree — you are almost always off by one segment.

Commands that live in the web app

Some operations are listed but not runnable from the CLI: OAuth connector setup, billing payments, SSO configuration, payment-method management, and similar flows that need a browser or a human confirmation step. Running one prints where to go instead of failing:

autessa sms-consent create

SMS consent records are created from your company's SMS consent page in the web app.

They remain in the help tree deliberately, so discovery tells you the capability exists and where it lives, rather than leaving you to wonder whether you typed the name wrong. See Autessa CLI.

Related

• Autessa CLI
• Install and sign in
• Command surface
• Coding agents