Coding Agents

A self-describing CLI is an unusually good tool surface for a coding agent. There is no API spec to embed in a prompt and no client library to keep in sync — the agent runs help, reads what came back, and calls the right command. Give it the CLI in its shell, or add the hosted Autessa connector to your AI app, and it can build working Autessa systems end to end.

What it's for

• Building on Autessa from an agent session. "Create a table for support tickets, a triage tool, and an agent that uses it" is a task a coding agent can carry out directly, from your terminal.
• Editing custom apps. app pull and app push put a real React project on disk, which is exactly the shape a coding agent works best on.
• Migrations and bulk edits. Renaming across a hundred rows, restructuring a schema, updating a set of tools — the CLI's JSON in and JSON out composes with whatever the agent already does.

Why the CLI suits agents

• Discovery is built in. autessa help → autessa <namespace> help → autessa <namespace> <command> help gives an agent the full argument list, types and response shape without you priming it.
• Incomplete commands teach instead of failing. Running a command that still needs arguments prints its help. An agent that guesses gets a correction, not a stack trace.
• Errors are actionable. Validation failures come back as field tables; type errors name the JSON path.
• The surface is current by construction. It is generated from the live SDK manifest, so an agent never works from a stale spec.
• Guardrails are server-side. Scope, permissions, validation and call budget are enforced by the SDK. An agent cannot exceed what your account can do.

How to set it up

1. Choose how the agent connects

There are two ways in. Both act as you, under your permissions, so pick whichever fits your agent.

	CLI in the agent's shell	Autessa connector (MCP)
How the agent calls it	Runs autessa … in a terminal	Calls the autessa tool with the command as a string
Works with	Any agent that can run terminal commands	Any AI app that supports custom MCP connectors: web, desktop, mobile or command line
Install	Node 18+ and the CLI	Nothing: you add a URL
Sign-in	autessa login in a terminal, about every eight hours	Once in the browser; the connection stays signed in
Company	Chosen at autessa login, or per command with --profile	Chosen when you connect, switchable from the chat
Piping (jq, scripts, $(…)), local files	Yes	No: one command per call, results as JSON
Best for	Scripted builds, bulk edits, uploads	Chat and IDE assistants, and agents with no shell access

2. Set it up

CLI in the agent's shell

npm install -g @autessa/cli
autessa login
autessa status

The agent inherits your session. The credential is tenant-scoped and expires in roughly eight hours — when it lapses, the agent will see "Session expired" and you re-run autessa login. If the agent can run autessa status in its terminal, it is connected.

Autessa connector (MCP)

Autessa hosts an MCP server at:

https://api.autessa.com/autessa_mcp

It works with any AI app that supports custom MCP connectors. The steps are the same everywhere; only the names of the menus differ:

1. Add the connector. In your AI app's settings, find where you add connectors (sometimes called integrations, apps or MCP servers) and add a custom one. Name it Autessa and paste the URL. In a command-line agent, this is usually a single "add MCP server" command that takes a name and the URL.
2. Choose the sign-in options if asked. Pick OAuth as the sign-in method. If the app asks how it should identify itself, any option works; the default is fine.
3. Connect. Your browser opens Autessa. Sign in if you need to, choose the company the agent should start in, and click Allow.
4. Try it. Ask: "List my Autessa companies."

The app never sees your password: it receives a token that only works on this connector, and you can disconnect it at any time from the app's connector settings. Some apps only offer custom connectors on certain plans, or need a workspace admin to add them first.

The connector gives the agent two tools:

Tool	What it does
autessa	Runs one command. Its args input is everything you'd type after the word autessa, e.g. skills, help, autessadb tables create help. Every result ends with the company it ran in.
autessa_company	Lists the companies you belong to, or switches which one autessa acts in. A switch applies to every later call on that connection.

The agent discovers commands the same way you do, so the tool list stays at two however many commands the platform adds.

Some CLI conveniences need your machine and aren't available through the connector: local files (@file arguments, uploads and downloads, app pull/app push to disk), the drive and analytics shorthand, and --output formatting. Pass JSON inline in single quotes instead. For anything file-based, use the CLI.

Check the connection

Ask the agent: "Use Autessa to list my companies." Over the connector it calls autessa_company and marks the company it's acting in. With the CLI, ask it to run autessa status. If something's off, see Troubleshooting the connector.

3. Have the agent read the built-in guide

The CLI ships a guide written for models rather than humans:

autessa skills

It prints the conventions that matter most when an agent is improvising — prefer Autessa connectors over external tools, prefer purpose-built tool types over hand-written scripts, keep apps in draft until asked to publish, and how to recover from each error class. Have the agent read it once at the start of a session.

Over the connector this is the autessa tool with args: "skills". The connector already tells the agent to begin there, but the standing instructions below make sure of it.

4. Give the agent standing instructions

Most coding agents read a project instructions file from the repo root (CLAUDE.md, AGENTS.md, .cursor/rules, .github/copilot-instructions.md, GEMINI.md). Add something like this to yours:

## Autessa

This project builds on Autessa. Use the `autessa` CLI for all platform work.

- Run `autessa skills` once before your first Autessa command.
- Discover commands with `autessa help`, `autessa <ns> help`, `autessa <ns> <cmd> help`.
  Never guess flags — a command with missing arguments prints its own help.
- Use Autessa connectors for third-party services (Gmail, HubSpot, Notion, QuickBooks…).
  Do not use curl or vendor CLIs — the connector holds the credentials.
- When giving an agent a capability, pick a purpose-built tool type from
  `autessa tool-types categories`. Use AUTESSA_SCRIPT only when nothing else fits.
- Custom apps: push to the draft freely. NEVER run `autessa app publish` unless I
  explicitly ask to launch / ship / deploy / go live.
- Don't report an app as live until `app publish-status` reports SUCCESS.
- Prefer `--output json` (the default) and parse with jq. Never parse `--output table`.

If the agent uses the connector, change the first lines so it reaches for the tools rather than the shell:

## Autessa

This project builds on Autessa. Use the Autessa connector's `autessa` tool for all platform work.
Its `args` is everything after the word `autessa`, e.g. `help` or `agents all`.

- Call it with `skills` once before your first Autessa command.
- Discover commands with `help`, `<ns> help`, `<ns> <cmd> help`.
  Never guess flags — a command with missing arguments prints its own help.
- Pass JSON inline in single quotes (`--schema '{...}'`). There are no local files.
- Check which company you're in with `autessa_company` before writing anything, and
  never switch companies unless I ask.

Then keep the connector, tool-type and publishing rules from the first version.

5. Reduce permission prompts

If your agent asks before each shell command, allowlisting the read-only ones keeps a session moving while leaving writes gated. The pattern to allow is the help tree plus the list commands — autessa help, autessa * help, autessa * all — while leaving create, update, publish and delete to prompt. Exactly how you express that depends on your agent's permission settings.

Over the connector, apps grant permission per tool, and every command goes through the one autessa tool. So you can't allow reads and gate writes the way you can with shell patterns. You have two choices:

• Approve each call. This is the default in most apps, and the safe choice against a production company.
• Always allow the tool. Use this when the agent works in a sandbox company. Most apps offer an "always allow" option at the first prompt or in their connector settings.

Keep autessa_company on approval even if you always allow autessa. Then the agent can work freely in the company you picked, but can't move itself into another one without asking you.

Conventions worth encoding

These are the mistakes agents make most often against this CLI. Each one is cheap to prevent with an instruction and expensive to debug after the fact.

Publishing is a deploy

The single most important rule. autessa app publish serves the draft to everyone with access, replacing what was live. An agent that publishes reflexively after each edit will ship half-finished work.

Encode: stay in the draft; publish only on an explicit request to go live. The same caution applies more mildly to agents publish and tools publish, which create new live versions.

Connectors, not curl

If the task touches a third-party service, the Autessa connector already holds the authenticated credentials. An agent reaching for curl or a vendor CLI will either fail or route around the credential store.

autessa connectors              # what's available
autessa gmail help              # a connector's commands

Connectors that need OAuth are created in the browser — an agent should tell you to connect one rather than trying.

Native tool types, not scripts

A new draft tool starts as an AUTESSA_SCRIPT hello-world, which nudges an agent toward writing code. The platform ships hundreds of purpose-built types with the right config fields and auth already wired:

autessa tool-types categories
autessa tool-types AUTESSADB_QUERY_TABLE

Reach for AUTESSA_SCRIPT only when nothing fits.

Read the response, don't assume the write

Several update methods normalize what you send — argument definitions store as isRequired and argumentSchema, for instance. The response is the source of truth for what was saved. An agent that assumes its input round-tripped verbatim will build on a wrong picture.

SDK_UNKNOWN_ENDPOINT means stale, not missing

The CLI auto-refreshes its manifest on this error. The correct reaction is to re-run, and check autessa <namespace> help if a name changed — not to conclude the command does not exist and improvise something else.

A worked example

What a well-instructed agent session looks like against this CLI:

# 1. orient
autessa skills
autessa status

# 2. discover, don't guess
autessa tool-types categories
autessa tool-types AUTESSADB_QUERY_TABLE
autessa tools create help

# 3. build
TABLE_ID=$(autessa autessadb tables create --tableName tickets --schema '{...}' | jq -r '.tableId')
TOOL_ID=$(autessa tools create --toolName find_tickets --toolDescription "..." | jq -r '.tool.toolId')
autessa tools update --toolId "$TOOL_ID" --updatedTool '{...}'
autessa tools publish --toolId "$TOOL_ID"

# 4. verify against the real thing
autessa tools execute --toolId "$TOOL_ID" --variables '{...}'
autessa tools history list --toolId "$TOOL_ID"

# 5. hand off
autessa app visible-urls --appId "$APP_ID"

Step 4 matters more than it looks. The agent can run what it built and read the execution history back, so it verifies against real platform behavior rather than reporting success from a 201.

Step 5 is the handoff: every id printed is live in the builder, so you can open what the agent made and check it in a UI rather than reading a transcript. That is the practical value of everything being immediately auditable — the agent works headless, and you review in the browser.

The same session over the connector

Over the connector the steps are identical. The only difference is that each command is a tool call, and the agent reads ids out of the JSON responses instead of capturing them with $(… | jq). Rows are autessa tool calls unless noted:

#	Tool call args	What the agent does with the result
1	skills	Reads the conventions
1	autessa_company with action: "list"	Confirms the company before writing anything
2	tool-types AUTESSADB_QUERY_TABLE	Learns the tool type's config fields
2	tools create help	Learns the arguments
3	autessadb tables create --tableName tickets --schema '{...}'	Notes tableId from the response
3	tools create --toolName find_tickets --toolDescription "..."	Notes tool.toolId
3	tools update --toolId 123 --updatedTool '{...}'	Checks the saved shape in the response
3	tools publish --toolId 123
4	tools execute --toolId 123 --variables '{...}'	Verifies real output
5	app visible-urls --appId 45	Hands you the links

Troubleshooting the connector

The tools don't show up, or the connector says it failed.

• Check the URL is exactly https://api.autessa.com/autessa_mcp.
• Finish the sign-in: use the connect or authenticate option in your app's connector settings. Until you've signed in, the app has no tools to show.
• autessa mcp in the CLI is unrelated: it's the command group for managing the MCP servers your Autessa agents connect to.

The browser says "Couldn't connect to Autessa". The sign-in link expired (it lasts ten minutes) or came from an app the connector doesn't recognize. Start connecting again from the app.

The app asks you to sign in again. A connection stays signed in for 30 days after it was last used, refreshing on its own. After a longer gap, or if you disconnected it, the app asks you to sign in again; that's expected.

The agent is working in the wrong company. Ask it to list your companies with autessa_company; the current one is marked. Ask it to switch, or disconnect and reconnect to pick again. If you've been removed from a company, the connector moves to your default company on its own.

A command with JSON fails to parse. Arguments are split on spaces, and only '…' and "…" group words together. There are no backslash escapes. Wrap JSON in single quotes.

A command needs a file, or --output table is ignored. The connector has no access to your machine and always returns JSON. Use the CLI for uploads, downloads, @file arguments, and the drive and analytics shorthand.

Autessa's own agents

Separately from driving the CLI with an external coding agent, Autessa ships assistants inside the builder — the AutoBots: an agentic copilot for building agents and tools, a database copilot, a script copilot, and Vibecode for custom apps. The two approaches compose: build the scaffolding headless from your terminal, then refine in the builder with the copilots, or the reverse.

Related

• Autessa CLI
• Install and sign in
• Discovering commands
• Custom apps
• AutoBots