47Command Reference

This chapter gathers every command in one place. Most of Gridtop is worked with the pointer, but two things are worked with words typed in an exact form, and both are listed here in full: the Terminal (chapter 31), where you type commands yourself, and the agent tools, the actions an agent can take on your Gridtop. The agent tools are, taken together, Gridtop's API (application programming interface): the fixed set of named actions, each with its named inputs, through which one program asks another to do something. An agent never touches your Gridtop in any other way.

The chapter ends with a short selection of commands that belong to your hosting rather than to Gridtop: the Linux shell commands of cPanel's own terminal, and the SQL statements that read and change a website's database. They are included because an operator of a Gridtop-hosted site will want them sooner or later, and because several of them pair naturally with Gridtop's own.

Read 47.1 first; it explains how the entries are written. The rest is reference, to be consulted rather than read through.

47.1 How to Read This Chapter

Every command is shown in code, exactly as you type it. Within a command:

Quoting. A command is split into words at its spaces. A name that itself contains spaces must be put in double quotes, so that it is read as one word: new agent "Landotronix Writer". The web command (47.3) also accepts single quotes and backticks, because what it carries often contains double quotes of its own.

Capitals. Commands do not mind capitals: DIR, Dir and dir are the same command. The names of objects on the grid are matched without regard to capitals either. File names on your website's server are another matter: the server runs Linux, where Logo.png and logo.png are two different files.

Examples use Landotronix, the example business of this manual, its website landotronix.com, and an agent called Site Builder.

47.2 The Terminal's Gridtop Tab

The Gridtop tab is the Terminal's first, blue tab. It works on Gridtop itself: your drive, the objects on the grid, their connections and rules. Its prompt shows where you are on your drive, for example A:/Agentic Matrix/Gridtop>, and it opens there.

Moving about and reading the drive

Objects, connections and rules

The Terminal itself

Runtime and server commands

These reach Gridtop's runtime: the part of the server that does work on your drive's files for you. What it can do depends on what your hosting has installed, so start with runtime.

Three more names, schedule, move and color, are reserved: typed, they answer that they are not yet available. run with an agent's name opens its chatbox.

Locking onto an object

Locking makes one object on the grid the subject of the commands that follow, in the way that cd makes a folder the place they work in. Type cd, a space, #, the object's type, a colon and its name:

cd #Agent:Site Builder … or, with the quotes a name with spaces needs, cd "#Agent:Site Builder"

The prompt now ends with the object, A:/Agentic Matrix/Gridtop/#Agent:Site Builder>. While you are locked on, dir with nothing after it lists the object's connections and the rules applied to it; info, chat, set and rules on / rules off act on it without being told its name; and rules add applies the new rule to it. cd .. releases it. Any other cd releases it too.

The type before the colon is for your own reading; Gridtop finds the object by its name, or by its id.

Forwarding to the cPanel and SQL tabs

From the Gridtop tab you can hand a command to one of the other two tabs without leaving it. Type cpanel or sql and then the command:

cpanel ls public_html

The Terminal asks first: Send to cPanel: ls public_html ? (y/n). Type y (or yes) and the other tab runs it; anything else, and the Terminal answers Not sent. If the other tab is itself waiting for a yes or no, it tells you to answer there first (31.2).

Keys

47.3 web: Editing a Site from the Terminal

The web command makes the same exact, small changes to a staged version of a website that the Web Editor makes (chapter 27) and that agents make with the website_editor tool (47.6). It is the tool itself, typed: every change you make with web is one step in the version's Undo history, and plays in its preview if the preview is open, as an agent's edits do (27.7).

web works on a staged version, never on the live site. It changes the version showing in the website's preview; if none is, the newest staged version (26.6).

Choosing the site

web use <domain> [<page>]

chooses the website and the page that the commands which follow work on. The page is its address on the site: / (the home page, the default), /about.php, /services/. web use alone tells you what is chosen.

web use landotronix.com /contact.php

The commands

A selector names the element to change. Section 47.7 explains selectors in full; in short, #id, .class and tag names, as in a stylesheet.

Quoting

Anything that contains spaces is put in quotes. web accepts three kinds, so that what is inside may hold the other two:

• double quotes: "nav .phone"
• single quotes: '<p class="note">Open Saturdays.</p>'
• backticks: ` <a href="/quote.php" title='Free quote'>Quote</a> `

Attributes. In attr and wrap, write each attribute as name=value, with no quotes around the value. A value that contains spaces is quoted whole, name and all:

web attr "#crew-photo" "alt=The Landotronix crew at work" loading=lazy

css in detail

web css changes the rule with that exact selector where it already is, setting the properties you give and leaving the rest; if there is no such rule, it adds one. A property given with an empty value ("color: ") is removed from the rule.

• Where it is written. Unless you say otherwise, in the first stylesheet the page links from its own site (not colors.css, which holds the palette). file <name>.css names another stylesheet of the version; page writes it into the page's own <style> block.
• For one screen size. media "(max-width: 760px)" writes the rule inside that @media block, making the block if there is none.

web css ".hero h1" "font-size: 2.6rem; letter-spacing: .02em" web css "nav" "display: none" media "(max-width: 760px)"

What it answers

Each change answers with what it did and in which file, for example Removed <div#promo.banner> "Fall sale" (index.php) v3, so that you can see it found the element you meant. No change. means the page already was as asked. If the change cannot be made, it says why and changes nothing (47.6).

47.4 The cPanel and SQL Tabs

The cPanel tab

The cPanel tab (amber) works on your websites' files on the server, through cPanel. It is not a Linux shell: it understands only the commands below, each carried out for you through cPanel. For a full shell, see 47.8.

Begin with sites, then choose one with site; the prompt then shows where you are, with ~ for your hosting account's home folder, for example cPanel:~/public_html>. Paths may be absolute (/home/...), start from home (~/public_html/img), or be relative to where you are, with .. for the folder above.

There is no delete command in the cPanel tab. Files on a website are deleted in cPanel itself, or with rm in a shell (47.8).

The SQL tab

The SQL tab (cyan) works on your websites' databases. A database is where a site keeps what it records: its orders, its sign-ups, its messages from the contact form, in tables of rows and columns. SQL (Structured Query Language) is the language in which you ask a database for its rows, or change them.

How SQL is run. Every line that is not one of the commands above is sent to the database as one SQL statement, of up to 20,000 characters; a closing semicolon is optional. Results come back as a table, with the number of rows and the time taken; the first 200 rows are shown.

Read-only until you say otherwise. The tab starts read-only. A statement that begins with SELECT, SHOW, DESCRIBE, DESC, EXPLAIN or WITH reads, and is run in a read-only transaction, so that it cannot change anything even by accident. Any other statement changes the database: the tab refuses it with That changes the database. Type write on first. After write on, the prompt shows (write), and each change still asks Run this change on database ? before it runs. Every change is recorded in your account's security log.

Because use and desc are the tab's own commands, they are not sent as SQL: use them as above.

The Bash tab

In Autocomputing '26, the Bash tab (green) has no commands of its own beyond cls and clear: every other line is run, one at a time, by the shell on your own PC (31.3). It does not reach your hosting.

47.5 Agent Tools: Gridtop's API

An agent works by calling tools. Each tool has a name, a description that tells the agent what it is for, and named parameters, the inputs the agent fills in when it calls it. You do not call these yourself; you ask an agent in plain words, and it chooses the tools. This section lists them so that you know what an agent can do, what it needs from you, and what each step in its tool trace (19.1) means.

Permissions. Each tool needs one of the agent's permissions (15.2), shown in the tables as Read, Edit, Stage, Make Connections or Configure Agents; Integration tools may need Send Outside. A dash means the tool needs no permission of its own. When an agent lacks the permission a tool needs, it asks you in its chat.

Connections give access. Two rules apply on top of permissions (16.8). An agent reaches a website's files only when it is connected to that Web Front by a line, or the file was attached to your message. And it reads, sets up and saves only the Tasks, Roles, Skills and Tools joined to it by a line, including any it made.

Parameters are written name (type): an agent fills a string with text, a number or integer with a number, a boolean with true or false, an array with a list, and an object with named values. Required parameters are marked required.

Files and folders on your drive

The Editor

These work on the file open in the Editor (chapter 23). A staged website file (one in Staging/vn) is saved to the drive as the agent edits it, so the preview shows the change; any other file waits, as unsaved changes, for you to save (23.5).

Websites

preview_inspect. The files of a site say what a page should look like; this tool reports what it does look like, measured in your open preview. The agent names the element by a CSS selector, or by some of its visible text (the innermost element containing that text is taken). For each element found, up to three, it returns: a selector for it, its tag, id, classes and text; its box (position, width, height, and whether it is on the screen); its computed look (colours as #RRGGBB, fonts and sizes, spacing, border, shadow, display and layout); the background it actually shows, and which element paints it; its inline style and old-style HTML attributes; and every CSS rule that applies to it, up to 40, each with the file it comes from. The page's address, title, window size and stylesheets come with it. When nothing matches, it lists the ids on the page and its landmarks (header, nav, main, sections, footer) to try instead. It reads only, and works only while a preview is open, with a Gridtop panel in it (Add Agent, 27.7).

Databases

An agent reads a database only when you have attached it to the agent, in the Server app: the database's window, its Agents tab (28.3). No agent tool changes a database.

Gridtop and its objects

Other agents, and you

Media and the runtime

Chess

play_chess (opponent: agent or computer), chess_board (none) and chess_move (move, in UCI notation, for example e7e5) let an agent start a game and play it (19.4). They are offered to an agent only while it is playing, or when your last message mentions chess. None needs a permission.

Tools you make, and Integration tools

A Tool object of your own (16.4) that is connected to an agent becomes one of its tools, under the function name you gave it, with the inputs you defined. A Tool marked to ask first asks before every run.

An agent connected to an Integration set up as a service it can work through gets that service's tools too, named after the kind, the Integration and the tool, for example mcp_… or stripe_…. A tool that only reads needs Read; one that changes things, Edit; one that sends something outside Autocomputing, Send Outside. Sending an invoice or a refund asks you every time. Chapter 32 describes the services.

Tools an outside agent sees

A program connected to your Gridtop with a key from the Harness app (32.3) works through Gridtop's MCP server, with these tools, as far as its key allows: drive_list and drive_read (Read the drive), drive_write (Write to the drive), list_agents, and ask_agent (Message your agents), which puts a question to one of your agents and returns its answer. The drive tools never reach the Receptaculum, refuse blocked file types, and take up to 2 MB a file. A key set to act as one of your agents also takes that agent's permissions, standing rules and lines.

Time limits. A tool that does not finish within 45 seconds is stopped and the agent told so, unless the tool allows itself longer: instruct_agent three minutes, hardline_job two.

47.6 website_editor in Full

website_editor is the tool with which an agent makes exact changes to a staged website: a word here, a colour there, a section moved, a column added. It shares its code with the Web Editor (chapter 27), so a person in the preview and an agent in a chat change a page in the same way, and land in the same Undo history. The Terminal's web command (47.3) types the same tool.

Changes land in the version showing in the preview; if none is, the newest staged version; or the version named. Each change is one step that Undo in the Web Editor, web undo, or the act undo takes back, and each plays in the open preview as it lands (27.7). The tool needs Stage.

Every call names a Web Front and an act. The parameters are these:

Reading acts

Content and layout acts

Structural acts

These change the page's source itself, element by element. Each finds its element with a selector (47.7), and each answers with what it matched, so that the result can be checked.

What the editor refuses

The structural acts are careful with your page, and refuse rather than guess. Nothing is changed when:

• The selector matches more than one element, or none. The answer lists the first few it matched, or says that nothing in the page's source matches, so that the selector can be made exact. (wrap, with a list, is the one act that takes several.)
• The element is printed by PHP. The editor reads the page's source as it is written in its file. An element that the page's PHP code prints when the page runs is not written there, and cannot be found; preview_inspect (47.5) shows the page as it is shown.
• The change would break the page's PHP. A .php page that parsed before the change and would not after it is left as it was: That change would break the page's PHP (line n: …). Nothing was changed.
• The new markup contains PHP, or is longer than 40,000 characters.
• An attribute is an event handler, such as onclick: attributes beginning with on are not written.
• There is no inside: set_html, prepend and append refuse an element that cannot hold anything, such as <img>.

47.7 Selectors the Editor Reads

A selector is a short description of one or more elements on a page, written in the language of stylesheets. h1 means every main heading; #quote-form the one element whose id is quote-form; .price every element of the class price; footer .phone an element of class phone somewhere inside the footer.

The structural acts (47.6) and web (47.3) read this part of the language:

Parts are combined as in a stylesheet: nav#main > a.button[href^="/"]:first-of-type. n is a plain number: odd, even and 2n+1 are not read.

Not read: the sibling signs + and ~, :not(), :hover and the other states, and ::before and ::after. An attribute value with a space in it cannot be matched exactly; match one of its words with ~=, or a part with *=.

47.8 Useful cPanel (Bash) Commands

The commands in this section are not Gridtop's. They are standard Linux shell commands, typed in the shell of your hosting account: a command line on the server itself, where the shell, called Bash, carries out each command you type. Run them in cPanel's own Terminal (in cPanel, Advanced ▸ Terminal) or over SSH. They do not work in the Terminal's cPanel tab (47.4), which knows only its own commands, nor in the Bash tab of Autocomputing '26 (31.3), which runs on your PC, not on the server.

In the shell, ~ is your account's home folder, and a website's files are usually in ~/public_html (the main domain) or a folder of the other domain's name. Change landotronix.com and the file names below for your own.

Finding your way

Space and permissions

Copies, archives and backups

PHP, logs and the live site

Deleting

Databases from the shell

A database in cPanel is named with your cPanel username in front: landotro_shop, for an account named landotro. To reach one from the shell you need a database user and its password, from cPanel's MySQL Databases; -p makes the shell ask for the password, rather than showing it on the screen.

47.9 Useful SQL

These statements work in the Terminal's SQL tab (47.4), in the Server app's database window (28.3), and in the mysql command line (47.8). Your hosting's databases are MySQL or MariaDB, which speak the same SQL. Replace the table and column names with your own; tables and desc in the SQL tab show what they are.

Reading

Statements that read change nothing, and the SQL tab runs them without write on.

Changing

Statements that change a database need write on in the SQL tab, and ask before each one. Before any change, take a backup (mysqldump, 47.8), and run the same WHERE as a SELECT first, to see exactly which rows it will touch.