ngsi [global options] command [common options] sub-command [options]

Convenience command

command sub-command sub-sub-commnand Description
admin log - print or set logging level for FIWARE Orion
trace - print, set or delete trace level for FIWARE Orion
semaphore - print semaphore for FIWARE Orion
metrics - print, reset or delete metrics for FIWARE Orion, Cygnus
statistics - print or delete statistics for FIWARE Orion, Cygnus
cacheStatistics - print or delete cache statistics for FIWARE Orion
appenders list list appenders
get get a appender
create create a appender
upadte update a appender
delete delete a appender
loggers list List loggers
get get a logger
create create a logger
update updata a logger
delete delete a logger
scorpio list List information paths
types Print types
localtypes Print local types
stats Print stats
health Print health
apis - - print endpoints of FWARE Open APIs
cp - - copy entities
wc - - print number of entities, subscriptions, registrations, or types
man - print URLs of document
health - print health status of FIWARE GEs
ls - list entities
rm - remove entities
receiver - notification receiver
regproxy - registration proxy
template subscription create template of subscription
registration create template of registration
version - print the version of Context Broker

NGSI command

command sub-command Description
append attrs append attributes
tattrs append attribute instance of temporal entity
create entity create entity
entities create entities
tentity create temporal entity
subscription create subscription
registration create registration
delete entity delete entity
entities delete entities
tentity delete temporal entity
attr delete attribute
tattr delete attribute of temporal entity
subscription delete subscription
registration delete registration
get entity get entity
entities get entities
tentity get temporal entity
attr get attribute
attrs get attributes
subscription get subscription
registration get registration
list types list types
entities list entties
tentities List temporal entities
subscription list subscription
registration list registration
replace entities replace entities
attrs replace attrs
update entities update entities
attr update attribute
tattr update attribute instance of temporal entity
attrs update attributes
subscription update subscription
upsert entity upsert entity
entities upsert entities

Time series command

command sub-command Description
hdelete attr delete all the data associated to certain attribute of certain entity
entity delete historical data of a certain entity
entities delete historical data of all entities of a certain type
hget attr get history of an attribute
attrs get history of attributes
entities list of all the entity id

Cygnus command

command sub-command Description
groupingrules list List grouping rules
create Create a grouping rule
update Update a grouping rule
delete Delete a grouping rule
namemappings list List name mappings
create Create a name mapping
delete Delete a name mapping

IoT Agent command

command sub-command Description
services list List configuration groups
create Create a configuration group
update Update a configuration group
delete Delete a configuration group
devices list List all devices
create Create a device
get Get a device
update Update a device
delete Delete a device

Context-Aware CEP command

command sub-command Description
rules list List all rules
create Creates a rule
get Get a rule
delete Delete a rule


command sub-command sub-sub-command Description
users list - List users
get - Get a user
create - Create a user
update - Update a user
delete - Delete a user
organizations list - List organizations
get - Get an organization
create - Create an organization
update - Update an organization
delete - Delete an organization
users list List users of an organization
get Get info of user organization relationship
add Add a user to an organization
remove Remove a user from an organization
applications list - List applications
get - Get an application
create - Create an application
update - Update an application
delete - Delete an application
roles list List roles
get Get a role
create Create a role
update Update a role
delete Delete a role
permissions List permissions associated to a role
assign Assign a permission to a role
unassign Delete a permission from a role
permissions list List permissions
get Get a permission
create Create a permission
update Update a permission
delete Delete a permission
organizations ilst List organizations in an application
get Get roles of an organization in an application
assign Assign a role to an organization
unassign Delete a role assignment from an organization
pep-proxies list List pep proxies
create Create a pep proxy
reset Reset a pep proxy
delete Delete a pep proxy list List trusted applications associated to an application
add Add a trusted application
delete Delete a trusted application
providers - - Print service providers

Management command

command sub-command Description
broker list list brokers
get get broker
add add broker
update update broker
delete delete broker
context list list @context
add add @context
update udpate @context
delete delete @context
server Serve @context
settings list list settings
delete delete settings
clear clear settings
server list list servers
get get server
add add server
update update server
delete delete server
token - manage token

Global Options

Options Description
--syslog LEVEL specify logging LEVEL (off, err, info, debug)
--stderr LEVEL specify logging LEVEL (off, err, info, debug)
--config FILE specify configuration FILE
--cache FILE specify cache FILE
--batch, -B don't use previous args (batch) (default: false)
--help show help (default: false)
--version, -v print the version (default: false)

Common options

Options Description
--host value, -h value specify host or alias
--token value specify oauth token
--service value, -s value specify FIWARE Service
--path value, -p value specify FIWARE ServicePath
--help show help (default: false)

DateTime options

Some commands have the following options for specifying the date and time:

  • expires {value}
  • fromDate {value}
  • toDate {value}

These options can have a value as shown:

Values Examples
ISO8601 YYYY-MM-DDThh🇲🇲ss.ssZ, YYYY-MM-DDThh🇲🇲ss.sssZ
year, years 1year, 3years, -5years
month, months 1month, 11months, -3months
day, days 1day, 3days, -10days
hour, hours 1hour, 5hours, -2hours
minute, minutes 1minute, 7minutes, -1minute

You can specify a negative value for a date and time in the past.


Specify a future date for an expiration date.

ngsi create --host orion subscription --idPattern ".*" --type Sensor \
--wAttrs temperature --nAttrs temperature --url http://orion:1026/ \
--expires 1day

To get historical data, specify a past date.

ngsi hget --host quantumleap attrs --id device001 --attrs A1,A2 --hLimit 3 \
--fromDate -5years --toDate -3years

--data option


ngsi create entity --keyValues \
--data ' {
      "name": "Lemonade",
      "size": "S",
      "price": 99


echo "{ \"id\":\"urn:ngsi-ld:Product:003\", \"type\":\"Product\", \"name\": \"Lemonade\", \"size\": \"S\", \"price\": 99 }" | ngsi create entity --keyValues --data @-
echo "{ \"id\":\"urn:ngsi-ld:Product:003\", \"type\":\"Product\", \"name\": \"Lemonade\", \"size\": \"S\", \"price\": 99 }" | ngsi create entity --keyValues --data stdin
echo '{ "id":"urn:ngsi-ld:Product:002", "type":"Product", "name": "Lemonade", "size": "S", "price": 99 }' | ngsi create entity --keyValues --data @-


ngsi create entity --keyValues --data @data.json


  "name": "Lemonade",
  "size": "S",
  "price": 99

Safe string

ngsi broker get -host orion

The value of the name attribute has forbidden characters.

ngsi create entity --keyValues \
--data ' {
      "name": "<Lemonade>",
      "size": "S",
      "price": 99
entityCreate006 400 Bad Request {"error":"BadRequest","description":"Invalid characters in attribute value"}

Create entity with --safeString on

ngsi create entity --keyValues --safeString on \
--data ' {
      "name": "<Lemonade>",
      "size": "S",
      "price": 99

Get an attribute value with --safeString off

ngsi get attr --id urn:ngsi-ld:Product:110 --attr name --safeString off

Get an attribute value with --safeString on

ngsi get attr --id urn:ngsi-ld:Product:110 --attr name --safeString on

Error message

An error message consists of a prefix and a body. E.g.

entityCreate006 400 Bad Request {"error":"BadReqest","description":"Invalid characters in attribute value"}

The error message has entityCreate006 as a prefix. A prefix consists of a Go function name and a position in the funciton. The function name is entityCreate. The position is 6th.

Detailed error information

You can get a detailed error information by running a command with the --stderr info option.

ngsi --stderr info version --host
version003 Get "": dial tcp connect: no route to host: no route to host
httpRequest003 Get "": dial tcp connect: no route to host
Get "": dial tcp connect: no route to host
dial tcp connect: no route to host
connect: no route to host
no route to host
abnormal termination
  • The first line shows that the version command was run.
  • The last line shows that the command terminated abnormally.
  • The lines between the first line and the last one shows a stack that Go functions were called.
  • The second line shows that a Go function that returned an error to a user.
  • The line before the last one shows the Go function where the error occurred. In the case, the function is not a function of the NGSI Go so that it doesn't have a prefix.