Skip to main content
Version: v5

Operations API Commands

Added in: v4.3.0

The Harper CLI supports executing operations from the Operations API directly from the command line. This enables powerful automation and scripting capabilities.

General Syntax​

harper <operation> <parameter>=<value>

Output Format:

  • Default: YAML
  • JSON: Pass json=true as a parameter

Supported Operations​

The following operations are available through the CLI. Argument values are JSON-parsed, so operations that take nested objects or arrays of objects work from the CLI as well. See Parameter Formatting for how to quote them.

Complete Operations List​

note

This is just a brief overview of all operations available as CLI commands. Review the respective operation documentation for more information on available arguments and expected behavior. Keep in mind that all operations options are converted to CLI arguments in the same way (using snake_case).

OperationDescriptionCategoryAvailable Since
describe_tableDescribe table structure and metadataDatabasev4.3.0
describe_allDescribe all databases and tablesDatabasev4.3.0
describe_databaseDescribe database structureDatabasev4.3.0
create_databaseCreate a new databaseDatabasev4.3.0
drop_databaseDelete a databaseDatabasev4.3.0
create_tableCreate a new tableDatabasev4.3.0
drop_tableDelete a tableDatabasev4.3.0
create_attributeCreate a table attributeDatabasev4.3.0
drop_attributeDelete a table attributeDatabasev4.3.0
search_by_idSearch records by IDDatav4.3.0
search_by_valueSearch records by attribute valueDatav4.3.0
insertInsert new recordsDatav4.4.9
updateUpdate existing recordsDatav4.4.9
upsertInsert or update recordsDatav4.4.9
deleteDelete recordsDatav4.3.0
sqlExecute SQL queriesDatav4.3.0
csv_file_loadLoad data from CSV fileDatav4.3.0
csv_url_loadLoad data from CSV URLDatav4.3.0
list_usersList all usersUsers & Rolesv4.3.0
add_userCreate a new userUsers & Rolesv4.3.0
alter_userModify user propertiesUsers & Rolesv4.3.0
drop_userDelete a userUsers & Rolesv4.3.0
list_rolesList all rolesUsers & Rolesv4.3.0
drop_roleDelete a roleUsers & Rolesv4.3.0
create_csrCreate certificate signing requestSecurityv4.4.0
sign_certificateSign a certificateSecurityv4.4.0
list_certificatesList SSL/TLS certificatesSecurityv4.4.0
add_certificateAdd SSL/TLS certificateSecurityv4.4.0
remove_certificateRemove SSL/TLS certificateSecurityv4.4.0
add_ssh_keyAdd SSH keyComponentsv4.4.0
get_ssh_keyGet SSH keyComponentsv4.7.2
update_ssh_keyUpdate SSH keyComponentsv4.4.0
delete_ssh_keyDelete SSH keyComponentsv4.4.0
list_ssh_keysList all SSH keysComponentsv4.4.0
set_ssh_known_hostsSet SSH known hostsComponentsv4.4.0
get_ssh_known_hostsGet SSH known hostsComponentsv4.4.0
cluster_get_routesGet cluster routing informationClusteringv4.3.0
cluster_networkGet cluster network statusClusteringv4.3.0
cluster_statusGet cluster statusClusteringv4.3.0
remove_nodeRemove node from clusterClusteringv4.3.0
add_componentAdd a componentComponentsv4.3.0
deploy_componentDeploy a componentComponentsv4.3.0
deploy (alias)Alias for deploy_componentComponentsv4.3.0
package_componentPackage a componentComponentsv4.3.0
package (alias)Alias for package_componentComponentsv4.3.0
drop_componentRemove a componentComponentsv4.3.0
get_componentsList all componentsComponentsv4.3.0
get_component_fileGet component file contentsComponentsv4.3.0
set_component_fileSet component file contentsComponentsv4.3.0
install_node_modulesInstall Node.js dependenciesComponentsv4.3.0
set_configurationUpdate configuration settingsConfigurationv4.3.0
get_configurationGet current configurationConfigurationv4.3.0
create_authentication_tokensCreate authentication tokensAuthenticationv4.3.0
refresh_operation_tokenRefresh operation tokenAuthenticationv4.3.0
restart_serviceRestart Harper serviceSystemv4.3.0
restartRestart Harper instanceSystemv4.3.0
system_informationGet system informationSystemv4.3.0
registration_infoGet registration informationLicensingv4.3.0
get_fingerprintGet instance fingerprintLicensingv4.3.0
set_licenseSet license keyLicensingv4.3.0
get_usage_licensesGet usage and license infoLicensingv4.7.3
create_backupCreate a managed database backupBackupsv5.2.0
list_backupsList managed backupsBackupsv5.2.0
verify_backupVerify a managed backup's integrityBackupsv5.2.0
delete_backupDelete a managed backupBackupsv5.2.0
purge_backupsDelete all but the newest backupsBackupsv5.2.0
restore_backupRestore a database from a backupBackupsv5.2.0
get_backupDownload a full database snapshotBackupsv5.2.0
get_jobGet job statusJobsv4.3.0
search_jobs_by_start_dateSearch jobs by start dateJobsv4.3.0
read_logRead application logsLoggingv4.3.0
read_transaction_logRead transaction logsLoggingv4.3.0
read_audit_logRead audit logsLoggingv4.3.0
delete_transaction_logs_beforeDelete old transaction logsLoggingv4.3.0
purge_streamPurge streaming dataMaintenancev4.3.0
delete_records_beforeDelete old recordsMaintenancev4.3.0
get_statusGet custom status informationStatusv4.6.0
set_statusSet custom status informationStatusv4.6.0
clear_statusClear custom status informationStatusv4.6.0

Command Aliases​

The following aliases are available for convenience:

  • deploy → deploy_component
  • package → package_component

For detailed parameter information for each operation, see the Operations API documentation.

Command Examples​

Database Operations​

Describe a database:

harper describe_database database=dev

Describe a table (with YAML output):

harper describe_table database=dev table=dog

Example Output:

schema: dev
name: dog
hash_attribute: id
audit: true
schema_defined: false
attributes:
  - attribute: id
    is_primary_key: true
  - attribute: name
    indexed: true
clustering_stream_name: 3307bb542e0081253klnfd3f1cf551b
record_count: 10
last_updated_record: 1724483231970.9949
tip

For detailed information on database and table structures, see the Database Reference.

Data Operations​

Search by ID (with JSON output):

harper search_by_id database=dev table=dog ids='["1"]' get_attributes='["*"]' json=true

Search by value:

harper search_by_value table=dog search_attribute=name search_value=harper get_attributes='["id", "name"]'
tip

For more information on querying data, see the REST Reference and GraphQL Querying.

Configuration Operations​

Set configuration:

harper set_configuration logging_level=error

Get configuration:

harper get_configuration
tip

For comprehensive configuration options, see the Configuration Reference.

Component Operations​

Deploy a component:

harper deploy_component project=my-cool-app package=https://github.com/HarperFast/application-template

Get all components:

harper get_components

Note: deploy is an alias for deploy_component:

harper deploy project=my-app package=https://github.com/user/repo
tip

For more information on components and applications, see the Components Reference.

User and Role Operations​

List users:

harper list_users

List roles:

harper list_roles
tip

For detailed information on users, roles, and authentication, see the Security Reference.

Remote Operations​

All CLI operations can be executed on remote Harper instances. See CLI Overview - Remote Operations for details on authentication and remote execution.

Remote Component Deployment​

When using remote operations, you can deploy a local component or application to the remote instance.

Deploy current directory:

If you omit the package parameter, the current directory will be packaged and deployed:

harper deploy target=https://server.com:9925

Note: deploy is an alias for deploy_component.

Deploy to clustered environment:

For clustered environments, use the replicated=true parameter to ensure the deployment is replicated to all nodes:

harper deploy target=https://server.com:9925 replicated=true

Restart after deployment (with replication):

After deploying to a clustered environment, restart all nodes to apply changes:

harper restart target=https://server.com:9925 replicated=true

For more information on Harper applications and components, see:

Parameter Formatting​

Every argument is split on the first = and the value is parsed as JSON. If the value is not valid JSON, it is passed through unchanged as a string. That single rule covers all of the parameter types below: database=dev fails to parse and stays the string "dev", json=true parses to the boolean true, and ids='["1","2"]' parses to an array.

The one exception is ref (used by deploy-by-reference), which is always taken as a raw string so that a numeric-looking git tag such as ref=1.0 is not rewritten into the number 1.

String Parameters​

Simple string values can be passed directly:

harper describe_table database=dev table=dog

Array Parameters​

Array parameters must be quoted and formatted as JSON:

harper search_by_id database=dev table=dog ids='["1","2","3"]'

Object Parameters​

Objects and arrays of objects are supported. Pass them as single-quoted JSON:

harper deploy_component project=my-app package=npm:@my-org/my-app@1.2.3 \
  credentials='[{"registry":"registry.my-org.com","secret":"deploy.my-app.registry.my-org.com"}]'

harper deploy setup=true prints exactly this credentials='[...]' form as the command to run after it seals a registry or git token, so an array-of-objects argument is the normal path for private-package deploys rather than an edge case.

Quoting rules:

  • Wrap the JSON in single quotes. Double quotes let the shell expand $, backticks, and history references inside the value; single quotes pass the JSON through intact.
  • The whole key=value pair is one shell argument, so no unescaped spaces outside the quotes. Compact JSON with no spaces after : and , avoids the problem entirely.
  • To embed a literal single quote inside the JSON, end the quoted run, escape it, and reopen: '{"name":"O'\''Brien"}'.
warning

Command-line arguments are not private. Anything you type appears in shell history, in process listings (ps), and in CI job logs. Prefer a stored secret reference (the secret field above) or an environment variable over inlining a plaintext token in an argument.

Boolean Parameters​

Boolean values can be passed as strings:

harper get_configuration json=true
harper deploy target=https://server.com:9925 replicated=true

Output Formatting​

YAML (Default)​

By default, CLI operation results are formatted as YAML for readability:

harper describe_table database=dev table=dog

JSON​

Pass json=true to get JSON output (useful for scripting):

harper describe_table database=dev table=dog json=true

Scripting and Automation​

The Operations API commands through the CLI are ideal for:

  • Build and deployment scripts
  • Automation workflows
  • CI/CD pipelines
  • Administrative tasks
  • Monitoring and health checks

Check status:

# Log in to the cluster
harper login https://cluster-node-1.example.com:9925

# Provide your cluster's username and password when prompted.

# Deploy component to remote cluster
harper deploy \
  target=https://cluster-node-1.example.com:9925 \
  replicated=true \
  package=https://github.com/myorg/my-component

# Restart the cluster
harper restart \
  target=https://cluster-node-1.example.com:9925 \
  replicated=true

# Check status
harper get_components \
  target=https://cluster-node-1.example.com:9925 \
  json=true

Limitations​

Nested objects and arrays of objects are not a limitation; see Object Parameters. The real constraints are about what an argument value can carry:

  • Raw binary bodies. An argument value is text, so an operation whose request body is raw binary has no general CLI form. The two that need one have dedicated handling: deploy_component packages and uploads the current directory when package is omitted, and get_backup streams the snapshot to a file. Any other binary payload has to go over HTTP.
  • Large payloads. There is no way to feed an argument value from stdin or a file, and the operating system caps total argument length. Bulk data such as an inline csv_data_load is better sent over HTTP.
  • Secrets on the command line. Arguments are visible in shell history, ps output, and CI logs. Use a stored secret reference or an environment variable instead of an inline token.

For these cases, use the Operations API directly via HTTP.

See Also​