Smarter by Design.Simpler for Business
API Commands
What Is API Commands?
API Commands is the command branch that manages the resources of TR7 (vService, Backend Service, profile, network, user, WAF, AGS, GTM…) from the command line. In practice it is the command line equivalent of what the panel does: the objects managed by clicking in the interface are listed, displayed, created, changed and deleted with commands over this branch.
The branch is derived from the REST interface of the panel: every resource becomes a node in the command tree and every operation on a resource becomes an action. The tree is explored with Tab; the field names, their descriptions and the option lists come from the same definitions as in the interface.
10 Resource Branches
ags · gtm · lb · network · settings…
The top-level commands that overlap with the configuration modules of the panel; each one is bound to a permission area.
5 Standard Actions
list · show · add · update · delete
The same, predictable set of operations on every collection resource; additionally
update-many on the resources that support it. Hierarchical tree
Discovery with Tab
It branches as resource → sub-resource → action → field; memorizing is not needed.
Field-Based Permission
viewing · changing
The read commands require the permission to see the field, and the writing commands the permission to change the field.
Short syntax:
<resource> [sub-resource …] <action> [<id>] [required-field value …] [--optional-field value …]The Command Pattern
An API command consists of a hierarchical path that targets a resource and an action to be run on that resource. The path narrows from left to right: it goes down from the most general resource (lb, ags, network…) to the sub-resource and from there to the action. The fields are written after the action.
How are the fields written?
The fields given to an action are of two kinds; the form shows whether the field is required or not:
field <value>
Required — it is written without a prefix and appears red in the completion list. The required fields are asked for in order: until one is given, the other fields are not listed.
--field <value>
Optional — it is written with the
-- prefix. If it is not given, the field stays with its default value.In the actions that target a record, the id of the record is also required. show and delete take the id right after the action, without a field name being written; update, on the other hand, asks for the id with the id field and does not list the other fields until the id is given. The id field is a selection list: Tab shows the existing records with their names.
The field types
| Type | How it is written |
|---|---|
| text | A free text value |
| number / port | A numeric value |
| boolean | It takes the value true or false |
| selection | One of the predefined values (Tab lists them) |
| multiple selection | Every selection with a separate index: --field.0, --field.1 |
| list | A multi-value field; the items are written with an index: --field.0.subField |
| duration | A time interval value |
| address | An IP address, a network block or an address/port pair (addr.ip, addr.port) |
| password | It is asked for on a separate line, without being shown on the screen |
The values that carry special characters require quotes
The command line considers some signs as separators. If a value that contains these signs is written without being put in double quotes, the command is parsed incorrectly:
| Sign | If it is written without quotes |
|---|---|
( ) | The value is split into parts; it must be written in the form "%AGS_USER_INPUT(username)" |
# | The rest of the line is considered a comment and disappears; it must be written in the form "#2563eb" |
; | The value is split here |
| a space | The value is separated into more than one part |
The values that contain an address, a path and a slash can be written without quotes.
Discovery
Tab completes the sub-commands and the fields at the current position. When ? is written at the end of the line and Enter is pressed, the fields that can be used at that position are listed as a table with Parameter / Description columns and the command is not run; memorizing which field is required is not needed.
The Actions
Every resource that holds a collection is managed with the same set of actions. On the single-object (setting) resources there are only show and update; on some resources add or delete is not defined.
| Action | Its function | Note |
|---|---|---|
list | Lists all the resources with the id and name columns | Reading |
show <id> | Shows the detail of a single record | Reading |
add <fields> | Creates a new record | The required fields without a prefix, the optional fields with the -- prefix |
update id <id> [fields] | Updates the existing record | Only the given fields change, the others are preserved |
delete <id> | Deletes the specified record | More than one id can be written one after another in the same command |
The subtleties of writing the update fields. The update reads the existing record and writes over it; for this reason only the fields that will change are given. Two additional flags are displayed only in the update: --field.delete empties the field, and on the multiple selection fields --field.all marks all the usable options. Since the password fields are not read back from the old record, they are asked for again in the update as well.
Bulk Update (update-many)
update-many applies the same change to many records at once. It is present on eight resources: lb service, lb backend, lb backend-group, lb hc, lb threat-protection, network ip, waf host-groups, waf options.
How it is written. The first field written after the command is target; it is the only required field.
| Field | Status | Value |
|---|---|---|
target | Required | selected — the records selected from the list · all — the whole collection |
--ids.N | Conditional | The target ids for target selected. It is not suggested in the Tab list: the targets are marked from the selection list. In a script and in a pipeline it is written manually. |
--onError | Optional | abort (default) — if even one of the targets does not pass the validation, nothing is written · skip — the targets that pass are written |
The target selection list. When target selected is written and no id is given, a list with check boxes opens right before the command runs. The space key marks, Ctrl+A marks all the ones on the screen, typing a letter filters the list, and Esc first clears the filter and then exits the list. At least one record must be marked. In a run without a terminal (a script or a pipeline) the list cannot be opened; the targets must be written in the form --ids.0 --ids.1 ….
Confirmation. Every bulk update asks for confirmation before it is applied. The warning title is in the form "This operation will update ALL the objects in the collection" for target all and "N objects will be updated" for a selection; the second line counts the selected records with their names (after fifteen, the rest is collected as "+N more"). Nothing is written until the confirmation word is typed; when something wrong is typed, the operation is cancelled.
Which fields can be written in bulk. On the update-many node there are only the fields for which a single value can safely be written to many records. The following are not present in this command:
| What is left out | Its reason |
|---|---|
| The id, the name and the unique values | The same value cannot be written to more than one record |
| The type discriminator and the read-only fields | They determine the identity of the record, they cannot be changed in bulk afterwards |
| The list items that carry their own id | The item ids of one record cannot be copied to the others |
| The fields whose value depends on another field | The valid value changes according to the value of the sibling field |
| The file and free-form object fields | They carry a structure, not a value |
The fields bound to a condition are not in this list: if a field is not active on a target, it is skipped only on that target and the operation does not give an error.
The result report. The response reports every target separately: the result (applied, unchanged, skipped, failed), the applied fields, the fields that are not active on that object and the errors if any.
The actions outside CRUD. There is not only record management in the tree; some resources also offer their own operations as commands.
| Sample command | Its function |
|---|---|
lb service restart · lb service status list | Restarts the service, lists the running status |
lb certificate create-csr · lb certificate renew-internal | Produces a certificate request, renews the internally produced certificate |
settings backup create · settings backup apply | Creates a backup, applies the backup |
settings update files · settings update apply | Lists the update files, applies the update |
profile info · profile change-password | Shows the information of the user who logs in, changes their password |
hw-mgmt configure | Applies the hardware configuration |
The commands that ask for confirmation
The commands that have an effect on the system that is hard to undo (the hardware configuration, applying an update, renewing an internal certificate, resetting the WAF rules and all the bulk updates) ask for confirmation before they run. The confirmation screen consists of a yellow warning title and the line Type "yes" to continue:; no change is made until the confirmation word is typed exactly. The screen language depends on the preference of the user who logs in: in the Turkish interface the confirmation word is evet.
The Command Tree
The top-level commands below make up the API branch. The descriptions without parentheses are the interface equivalents that appear in the ? output of the command.
| Command | The area it manages |
|---|---|
ags | AGS - AAM (Application Access Management) management — gateway, authentication, MFA, forms, security policies, SSO |
exit | Closes the session (the same as Ctrl + D) |
gtm | Global Traffic Manager — DNS-based global traffic management |
help | Shows the CLI usage guide |
history | Shows the command history |
hw-mgmt | Hardware management |
lb | Load Balancer management — vService, Backend Service, groups, conditions, actions, profiles, certificates |
network | Network management — interfaces, addresses, route tables, firewall rules |
profile | Profile management — the own information of the user who logs in |
settings | General settings — access, backup, directory/log forwarding, NTP, notification |
users | User management — device administrator accounts |
v-device | vDevice management |
waf | WAF management — protected services, host groups, rule library |
INFO
At the root level there are additionally logout (the CLI user logout) and sys-cmd, which runs the system tools.
The Output Format and Filtering
The output of the commands that return a response is received in the requested format and filtered:
| Option | Function |
|---|---|
--info | Shows the explanation of what it does, without running the command |
--output json | Single-line JSON |
--output jsonp | Indented, readable JSON |
--output tab · comma · semicolon | Plain text with the columns separated by a tab, a comma or a semicolon |
--output compact | A narrowed table |
--output default | A framed table (the default view) |
--filter <pattern> | Filters the output according to the pattern; the matching text is highlighted in green, the non-matching lines are not shown |
TIP
In order to filter, transform or write the output to a file further, Pipe Commands is used (| grep, | jq, | to-file…); at most 8 filters can be chained on one line.
Sample Scenarios
admin@TR7LBWAF01> lb service list # list all the vServices
admin@TR7LBWAF01> lb service show <id> # show the detail of one of them
admin@TR7LBWAF01> lb service list --output jsonp # get the output as readable JSON
admin@TR7LBWAF01> lb service list --filter portal # filter the result by a pattern
admin@TR7LBWAF01>
# the required fields are written without a prefix, in order
admin@TR7LBWAF01> lb backend add name web-01 zoneId <vDevice> namespace <route-table> \
addr.ip 10.20.0.15 addr.port 8080
admin@TR7LBWAF01> lb backend list # verify that it has been created
admin@TR7LBWAF01>
admin@TR7LBWAF01> lb backend update id <id> --name web-02 # only the field that changes
admin@TR7LBWAF01> lb service update-many target selected --waf true
admin@TR7LBWAF01> lb backend delete <id> <id-2> # delete one or many records
admin@TR7LBWAF01>
admin@TR7LBWAF01> lb service add --info # what the command does, see it without running
admin@TR7LBWAF01> lb ? # list the sub-commands with descriptions
admin@TR7LBWAF01> lb service add ? # list the fields at this position
admin@TR7LBWAF01>
Access and Permissions
Every top-level command is mapped to a permission area; whether the command will run or not is decided by the permission of the user in that area.
| Command branch | Permission area |
|---|---|
ags · lb | Load Balancer |
network | Network |
waf | WAF |
gtm | GTM |
users | Users |
settings · hw-mgmt | Settings |
profile · v-device | Not mapped; the server decides on the permission |
| Action type | The permission required |
|---|---|
Reading (list, show, status queries) | Viewing the area |
Writing (add, update, update-many, delete and the commands that run an operation) | Changing the area |
- The superAdmin role is outside these checks; it can read and write in all the branches.
- The readOnly role reads all the areas but cannot write in any area.
- The area roles (e.g. networkManager, trafficUser, wafManager) use only the branches that fall into their own areas; those that have the permission to change can write in that area.
- The
lbbranch covers the load balancing, WAF and certificate areas together; a user who has permission in one of these areas can enter the branch, and the server decides which resource they can access.
INFO
A command outside the permission is not run and a Permission denied. warning is returned (on a user whose interface language is Turkish, Yetkiniz bulunmamaktadır.). For the whole access model, the channel keys and the session limits, the Web CLI main page can be consulted.
