Data commands
excel · xml · json · csv · pdf · database
excel Excel
Reads and writes Excel workbooks: .xlsx files directly (Excel does not need to be installed), or through an installed Microsoft Excel with --engine:excel (any format Excel opens, macros, refreshing data, PDF export).
Actions (--action)
--action:open
| Parameter | Value | Default | Description |
|---|
--file required | text | | A file on the agent machine. |
--session required | text | | Name for this workbook, used by the following excel commands |
--sheet | text | | Sheet to activate |
--create | true / false | false | Create the file when it does not exist |
--engine | one of file, excel | file | file: reads and writes the .xlsx file itself (no Excel needed); excel: drives Microsoft Excel on the agent machine (needed for runmacro, refreshall, exportpdf and autofit; formulas are calculated by Excel) |
--visible | true / false | true | With --engine:excel: show the Excel window while the task works |
--action:readcell
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--col required | any value | | |
--row required | number | | |
--output required | variable name | | Variable that receives the result |
Puts a formula into a cell; readcell then gives its calculated value.
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--col required | any value | | |
--row required | number | | |
--formula required | text | | An Excel formula, e.g. =SUM(C2:C10) (written to the cell as it is, not calculated by Botream) |
--action:find
The cells holding a value, top to bottom, as records (Row, Column, ColumnLetter, Address, Value); an empty list when there is none.
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--value required | any value | | Value to look for (compared as text, ignoring case) |
--col | any value | | Search only this column (letter or number) |
--match | one of exact, contains | exact | |
--output required | variable name | | Variable that receives the result |
--action:writecell
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--col required | any value | | |
--row required | number | | |
--value required | any value | | |
--action:readrow
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--row required | number | | |
--output required | variable name | | Variable that receives the result |
--action:writerow
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--row required | number | | |
--data required | $variable$ | | |
--action:readcolumn
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--col required | any value | | |
--output required | variable name | | Variable that receives the result |
--action:readrange
The cells as a data table whose columns are the first row; with --header:false a list of rows (each a list of values).
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--range | text | | e.g. A1:D10; defaults to the used range |
--header | true / false | true | First row holds column names (rows become records) |
--output required | variable name | | Variable that receives the result |
--action:writerange
Writes a data table (its column names first), a list of records or a list of lists, starting at --range.
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--range required | text | | Top-left cell, e.g. A1 |
--data required | $variable$ | | |
--header | true / false | true | Write column names first (for record rows) |
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--range required | text | | Cell or range, e.g. B2 or A1:D1 |
--bold | true / false | | |
--italic | true / false | | |
--fontsize | number | | |
--fontcolor | text | | Hex color, e.g. #FF0000 |
--backcolor | text | | Hex color, e.g. #FFFF00 |
--numberformat | text | | e.g. 0.00 or dd.MM.yyyy |
--action:deleterow
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--row required | number | | |
--action:insertrow
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--row required | number | | |
--data | $variable$ | | |
--action:getrowcount
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--output required | variable name | | Variable that receives the result |
--action:getcolumncount
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--output required | variable name | | Variable that receives the result |
--action:getsheets
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--output required | variable name | | Variable that receives the result |
--action:createsheet
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--sheet required | text | | |
--action:deletesheet
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--sheet required | text | | |
--action:activatesheet
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--sheet required | text | | |
--action:save
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--action:saveas
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--file required | text | | A file on the agent machine. |
--action:close
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--save | true / false | false | Save changes before closing |
--action:runmacro
Runs a VBA macro of the workbook (needs --engine:excel); --output receives what a Function returns.
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--macro required | text | | The macro, e.g. Module1.FixFormats or FixFormats |
--args | any value | | Values passed to the macro: a list variable or comma-separated values |
--output | variable name | | Variable that receives the result |
--action:refreshall
Refreshes every data connection, query and pivot table of the workbook and waits until they are done (needs --engine:excel).
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--action:exportpdf
Saves the active sheet or the whole workbook as a PDF (needs --engine:excel).
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--file required | text | | The PDF to write, e.g. C:\Reports\Sales.pdf A file on the agent machine. |
--scope | one of sheet, workbook | sheet | sheet: the active sheet; workbook: every sheet |
--action:autofit
Makes the columns as wide as their contents (needs --engine:excel).
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the workbook was opened Names a excel session opened earlier. |
--range | text | | Columns or cells, e.g. A:D; the used range when empty |
Examples
excel --action:open --file:"C:\data.xlsx" --session:Invoices --sheet:"Sheet1"
excel --action:readcell --session:Invoices --row:1 --col:2 --output:cellValue
excel --action:writecell --session:Invoices --row:1 --col:2 --value:"Updated"
excel --action:writeformula --session:Invoices --row:10 --col:C --formula:"=SUM(C2:C9)"
excel --action:find --session:Invoices --value:$orderNo$ --col:A --match:exact --output:cells
excel --action:readrow --session:Invoices --row:1 --output:rowData
excel --action:writerow --session:Invoices --row:1 --data:$rowRecord$
excel --action:readcolumn --session:Invoices --col:"A" --output:colData
excel --action:readrange --session:Invoices --range:"A1:D10" --output:tableData
excel --action:writerange --session:Invoices --range:"A1" --data:$dataTable$
excel --action:deleterow --session:Invoices --row:5
excel --action:insertrow --session:Invoices --row:3 --data:$rowRecord$
excel --action:getrowcount --session:Invoices --output:rowCount
excel --action:getcolumncount --session:Invoices --output:colCount
excel --action:createsheet --session:Invoices --sheet:"NewSheet"
excel --action:deletesheet --session:Invoices --sheet:"OldSheet"
excel --action:activatesheet --session:Invoices --sheet:"Sheet2"
excel --action:getsheets --session:Invoices --output:sheetList
excel --action:save --session:Invoices
excel --action:saveas --session:Invoices --file:"C:\output.xlsx"
excel --action:close --session:Invoices
excel --action:open --file:"C:\Reports\Sales.xlsm" --session:Sales --engine:excel --visible:false
excel --action:refreshall --session:Sales
excel --action:runmacro --session:Sales --macro:"Module1.FormatReport" --args:"2026, 10" --output:macroResult
excel --action:autofit --session:Sales --range:"A:F"
excel --action:exportpdf --session:Sales --file:"C:\Reports\Sales.pdf" --scope:workbook
excel --action:close --session:Sales --save:true
xml XML
Reads and edits XML documents with XPath.
Actions (--action)
--action:open
| Parameter | Value | Default | Description |
|---|
--file required | text | | A file on the agent machine. |
--session required | text | | Name for this document, used by the following xml commands |
--action:create
| Parameter | Value | Default | Description |
|---|
--session required | text | | Name for this document, used by the following xml commands |
--root | text | | Root element name |
--text | text | | XML text to load instead of an empty document |
--action:getvalue
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the document was opened Names a xml session opened earlier. |
--xpath required | text | | XPath, e.g. /Orders/Order[@id="7"]/Total |
--output required | variable name | | Variable that receives the result |
--action:setvalue
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the document was opened Names a xml session opened earlier. |
--xpath required | text | | XPath, e.g. /Orders/Order[@id="7"]/Total |
--value required | any value | | |
--action:getattribute
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the document was opened Names a xml session opened earlier. |
--xpath required | text | | XPath, e.g. /Orders/Order[@id="7"]/Total |
--attribute required | text | | |
--output required | variable name | | Variable that receives the result |
--action:setattribute
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the document was opened Names a xml session opened earlier. |
--xpath required | text | | XPath, e.g. /Orders/Order[@id="7"]/Total |
--attribute required | text | | |
--value required | any value | | |
--action:removeattribute
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the document was opened Names a xml session opened earlier. |
--xpath required | text | | XPath, e.g. /Orders/Order[@id="7"]/Total |
--attribute required | text | | |
--action:getnodes
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the document was opened Names a xml session opened earlier. |
--xpath required | text | | XPath, e.g. /Orders/Order[@id="7"]/Total |
--output required | variable name | | Variable that receives the result |
--action:count
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the document was opened Names a xml session opened earlier. |
--xpath required | text | | XPath, e.g. /Orders/Order[@id="7"]/Total |
--output required | variable name | | Variable that receives the result |
--action:addnode
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the document was opened Names a xml session opened earlier. |
--xpath required | text | | Parent element XPath |
--name required | text | | New element name |
--value | any value | | |
--action:deletenode
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the document was opened Names a xml session opened earlier. |
--xpath required | text | | XPath, e.g. /Orders/Order[@id="7"]/Total |
--action:getxml
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the document was opened Names a xml session opened earlier. |
--xpath | text | | Element to return; whole document when empty |
--output required | variable name | | Variable that receives the result |
--action:save
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the document was opened Names a xml session opened earlier. |
--action:saveas
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the document was opened Names a xml session opened earlier. |
--file required | text | | A file on the agent machine. |
--action:close
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when the document was opened Names a xml session opened earlier. |
--save | true / false | false | Save changes before closing |
Examples
xml --action:open --file:"C:\orders.xml" --session:Orders
xml --action:create --session:Report --root:"Report"
xml --action:getvalue --session:Orders --xpath:"/Orders/Order[1]/Total" --output:total
xml --action:setvalue --session:Orders --xpath:"/Orders/Order[1]/Status" --value:"Shipped"
xml --action:getattribute --session:Orders --xpath:"/Orders/Order[1]" --attribute:"id" --output:orderId
xml --action:setattribute --session:Orders --xpath:"/Orders/Order[1]" --attribute:"checked" --value:"true"
xml --action:removeattribute --session:Orders --xpath:"/Orders/Order[1]" --attribute:"checked"
xml --action:getnodes --session:Orders --xpath:"/Orders/Order" --output:orders
xml --action:count --session:Orders --xpath:"/Orders/Order" --output:orderCount
xml --action:addnode --session:Report --xpath:"/Report" --name:"Line" --value:$total$
xml --action:deletenode --session:Orders --xpath:"/Orders/Order[@cancelled='true']"
xml --action:getxml --session:Report --output:reportXml
xml --action:save --session:Orders
xml --action:saveas --session:Report --file:"C:\report.xml"
xml --action:close --session:Orders
json JSON
Reads and builds JSON, e.g. the data a web service returned (restapi --output:$response$ → $response.Json$). Paths look like data.items[0].name.
Actions (--action)
--action:parse
Turns JSON text into an object or list.
| Parameter | Value | Default | Description |
|---|
--text required | any value | | JSON text or a $variable$ holding it |
--output required | variable name | | Variable that receives the result |
--action:readfile
Reads a .json file.
| Parameter | Value | Default | Description |
|---|
--file required | text | | A file on the agent machine. |
--encoding | text | utf-8 | |
--output required | variable name | | Variable that receives the result |
--action:getvalue
Reads the value at a path (an object or list stays one).
| Parameter | Value | Default | Description |
|---|
--source required | any value | | JSON: a variable (e.g. $response.Json$) or JSON text |
--path required | text | | e.g. data.items[0].name, items[$i$].price or ["key with spaces"] |
--default | any value | | Used when the path does not exist or is null; without it a missing path is an error |
--output required | variable name | | Variable that receives the result |
--action:setvalue
Sets the value at a path in a variable; missing objects on the way are created.
| Parameter | Value | Default | Description |
|---|
--name required | variable name | | Variable holding the JSON (created when it does not exist) |
--path required | text | | e.g. data.items[0].name, items[$i$].price or ["key with spaces"] |
--value required | any value | | |
--valuetype | one of auto, string, number, boolean, json | auto | auto: true/false, numbers and {…}/[…] get their JSON type; a $variable$ keeps its type |
--action:remove
Removes the key or list item at a path.
| Parameter | Value | Default | Description |
|---|
--name required | variable name | | Variable holding the JSON |
--path required | text | | e.g. data.items[0].name, items[$i$].price or ["key with spaces"] |
--action:count
| Parameter | Value | Default | Description |
|---|
--source required | any value | | JSON: a variable (e.g. $response.Json$) or JSON text |
--path | text | | e.g. data.items[0].name, items[$i$].price or ["key with spaces"]; the whole JSON when empty |
--output required | variable name | | Variable that receives the result |
--action:keys
| Parameter | Value | Default | Description |
|---|
--source required | any value | | JSON: a variable (e.g. $response.Json$) or JSON text |
--path | text | | e.g. data.items[0].name, items[$i$].price or ["key with spaces"]; the whole JSON when empty |
--output required | variable name | | Variable that receives the result |
--action:todatatable
Turns a list of objects into a data table (e.g. for excel writerange or loop).
| Parameter | Value | Default | Description |
|---|
--source required | any value | | JSON: a variable (e.g. $response.Json$) or JSON text |
--path | text | | e.g. data.items[0].name, items[$i$].price or ["key with spaces"]; the whole JSON when empty |
--output required | variable name | | Variable that receives the result |
--action:stringify
Turns an object or list into JSON text (e.g. a request body).
| Parameter | Value | Default | Description |
|---|
--source required | any value | | JSON: a variable (e.g. $response.Json$) or JSON text |
--indent | true / false | false | Multi-line, indented text |
--output required | variable name | | Variable that receives the result |
--action:writefile
Saves JSON to a file.
| Parameter | Value | Default | Description |
|---|
--source required | any value | | JSON: a variable (e.g. $response.Json$) or JSON text |
--file required | text | | A file on the agent machine. |
--indent | true / false | true | Multi-line, indented text |
--encoding | text | utf-8 | |
csv CSV
Reads CSV files into data tables and writes data tables as CSV. Every cell is read as text.
Actions (--action)
--action:read
| Parameter | Value | Default | Description |
|---|
--file required | text | | A file on the agent machine. |
--delimiter | text | auto | auto finds comma, semicolon, tab or |; or give the character (or its name: comma, semicolon, tab, pipe) |
--header | true / false | true | The first row holds the column names; otherwise they are Column1, Column2… |
--encoding | text | utf-8 | e.g. utf-8 or windows-1254 |
--output required | variable name | | Variable that receives the result |
--action:write
| Parameter | Value | Default | Description |
|---|
--data required | $variable$ | | A data table (or a list of records) |
--file required | text | | A file on the agent machine. |
--delimiter | text | , | One character (or its name: comma, semicolon, tab, pipe) |
--header | true / false | true | Write the column names as the first row |
--encoding | text | utf-8 | |
--append | true / false | false | Add the rows to an existing file (its header is not repeated) |
Examples
csv --action:read --file:"C:\Data\orders.csv" --output:orders
csv --action:read --file:"C:\Data\export.txt" --delimiter:tab --header:false --encoding:"windows-1254" --output:rows
csv --action:write --data:$orders$ --file:"C:\Out\orders.csv" --delimiter:";"
csv --action:write --data:$newRows$ --file:"C:\Out\orders.csv" --append:true
pdf PDF
Reads the text of PDF files and merges, splits or extracts their pages (no PDF program needed). Scanned pages are images and have no text.
Actions (--action)
--action:gettext
The text of the document, or of some of its pages.
| Parameter | Value | Default | Description |
|---|
--file required | text | | PDF file A file on the agent machine. |
--pages | text | | Page numbers and ranges, e.g. 1-3,5 or 4- (page 4 to the last); all pages when empty |
--password | text | | Password that opens the document, when it is protected |
--output required | variable name | | Variable that receives the result |
--action:getpagecount
The number of pages.
| Parameter | Value | Default | Description |
|---|
--file required | text | | PDF file A file on the agent machine. |
--password | text | | Password that opens the document, when it is protected |
--output required | variable name | | Variable that receives the result |
--action:getinfo
A record with PageCount, Title, Author, Subject, Keywords, Creator, Producer, CreatedDate, ModifiedDate and IsEncrypted.
| Parameter | Value | Default | Description |
|---|
--file required | text | | PDF file A file on the agent machine. |
--password | text | | Password that opens the document, when it is protected |
--output required | variable name | | Variable that receives the result |
--action:merge
Joins PDF files into one, in the given order.
| Parameter | Value | Default | Description |
|---|
--files required | any value | | A list variable (e.g. from folder listfiles) or comma-separated paths |
--destination required | text | | PDF file to write (replaced when it exists) A file on the agent machine. |
Writes some pages of a document to a new PDF, in the order given.
| Parameter | Value | Default | Description |
|---|
--file required | text | | PDF file A file on the agent machine. |
--pages required | text | | Page numbers and ranges, e.g. 1-3,5 or 4- (page 4 to the last) |
--destination required | text | | PDF file to write (replaced when it exists) A file on the agent machine. |
--password | text | | Password that opens the document, when it is protected |
--action:split
Writes every page to its own PDF (<name>_1.pdf, <name>_2.pdf, …); --output receives the list of files.
| Parameter | Value | Default | Description |
|---|
--file required | text | | PDF file A file on the agent machine. |
--folder required | text | | Folder for the page files (created when missing) A folder on the agent machine. |
--password | text | | Password that opens the document, when it is protected |
--output | variable name | | Variable that receives the result |
Examples
pdf --action:gettext --file:"C:\Invoices\2026-001.pdf" --output:text
pdf --action:gettext --file:$file.Path$ --pages:"1-3,5" --password:$pdfPassword$ --output:text
pdf --action:getpagecount --file:"C:\Invoices\2026-001.pdf" --output:pageCount
pdf --action:getinfo --file:"C:\Invoices\2026-001.pdf" --output:info
pdf --action:merge --files:$files$ --destination:"C:\Out\all.pdf"
pdf --action:merge --files:"C:\a.pdf, C:\b.pdf" --destination:"C:\Out\ab.pdf"
pdf --action:extractpages --file:"C:\report.pdf" --pages:"2-" --destination:"C:\Out\without-cover.pdf"
pdf --action:split --file:"C:\report.pdf" --folder:"C:\Out\pages" --output:pageFiles
database Database
Runs database queries; results are stored as datatable variables.
Parameters of every variant
| Parameter | Value | Default | Description |
|---|
--timeout | number | 30 | Timeout in seconds |
--retry | number | | Number of retry attempts. When not set, screen and file commands try once more after a passing problem (a page still loading, a covered element, a locked file); 0 turns that off |
--retryinterval | number | 1 | Seconds between retries |
Actions (--action)
--action:connect
| Parameter | Value | Default | Description |
|---|
--provider required | one of sqlserver, mysql, postgresql, oracle, sqlite | | |
--connectionstring required | text | | |
--session required | text | | Name for this connection, used by the following database commands |
--action:disconnect
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when connecting Names a database session opened earlier. |
--action:query
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when connecting Names a database session opened earlier. |
--query required | text | | |
--params | text | | Comma-separated name=value pairs, e.g. id=$id$,status=active |
--output | variable name | | Variable that receives the result |
--action:execute
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when connecting Names a database session opened earlier. |
--query required | text | | |
--params | text | | Comma-separated name=value pairs, e.g. id=$id$,status=active |
--output | variable name | | Variable that receives the result |
--action:callprocedure
| Parameter | Value | Default | Description |
|---|
--session required | text | | Session name given when connecting Names a database session opened earlier. |
--procedure required | text | | |
--params | text | | Comma-separated name=value pairs, e.g. id=$id$,status=active |
--output | variable name | | Variable that receives the result |
Examples
database --action:connect --provider:sqlserver --connectionstring:"Server=...;Database=...;" --session:Crm
database --action:query --session:Crm --query:"SELECT * FROM Users WHERE Status=@status" --params:"status=active" --output:resultTable
database --action:execute --session:Crm --query:"UPDATE Users SET Status=@status WHERE Id=@id" --params:"status=inactive,id=5" --output:affectedRows
database --action:callprocedure --session:Crm --procedure:"sp_ProcessOrder" --params:"orderId=123" --output:procResult
database --action:disconnect --session:Crm
