orcli

A command-line utility for working with Orchestrate's API.

Install

Install orcli using npm. If you don't have npm, get it by installing node.js.

npm install -g orcli

Examples

Authenticate once

# authenticates with a provided API key and saves it as the default
orcli use $YOUR_API_KEY
# authenticates with a provided API key and saves it under "jellykid"
orcli use $YOUR_API_KEY jellykid
# list saved API keys and their aliases
orcli ls
# uses an API key with the name "jellykid"
orcli use jellykid

Easier than cUrl

# list the first page of contents for the users collection
orcli get users
# insert an item from a JSON document
cat item.json | orcli post users
# insert using options
orcli post users --username=garbados --name="Diana Agrotera Thayer"
# upsert something at a specific key
cat garbados.json | orcli put users garbados
# conditional updates
cat garbados.json | orcli put users garbados --if-none-match  # insert if new
cat garbados.json | orcli put users garbados --if-match [ref] # update if latest
# partial updates
orcli patch users garbados add --is_a_jerk=false --is_a_babe=true
cat updates.json | orcli patch users garbados
# merge updates
orcli merge users garbados --is_a_jerk=true

Built for Orchestrate

# get every user in Portland, OR
orcli search users 'location:"Portland, OR"'
# no, like, get everyone in the vicinity
orcli search users 'location_coords:NEAR:{lat:122.6819 lon:45.52 near:100km}'
# what do your friends like?
orcli graph users garbados friends likes
# mark this moment, friend
orcli event users garbados timeline create --marked=true
# no, unmark it
orcli event users garbados timeline update [timestamp] [ordinal] --marked=false
# wait, forget i said anything
orcli event users garbados timeline delete [timestamp] [ordinal]
# know your data's past
orcli refs users garbados

Reference

Responses

Orcli returns everything in JSON, whether response headers, bodies, error messages, and even messages from tasks that don't touch the web. If you're going to work with JSON via command line a lot, check out jq.

Flags

All commands accept the following flags, which modify what information Orcli will print for the user.

Flags:

• --head: Print the response headers instead of the response body.
• --verbose: Print the response headers and response body.
• --silent: Print nothing unless something goes wrong.
• --api-key: Execute the command using a given API key, not what is set in the configuration file.

Flags not mentioned here or in methods by name (ex: --if-match) are considered querystring parameters, JSON field-value pairs, or other method-specific information. For example:

orcli put users garbados --username=garbados --name="Diana Agrotera Thayer"

This command inserts an item whose JSON body looks like this:

{
    "username": "garbados",
    "name": "Diana Agrotera Thayer"
}

If you want to turn off parsing default flags, use --, like this:

orcli put users garbados -- --silent=true

Rather than activate Orcli's 'silent' flag, it treats --silent=true as an attribute of the PUT request, so that the updated user looks like this:

{
    "silent": true
}

Authentication and API Keys

orcli use [key] (alias)

Sets the current API key, and tests to ensure it's valid.

orcli use 1p03-11827-134713-anfe
# now using an unnamed key
orcli use some-bad-key
# ping unsuccessful: 401

Using an API key writes it to ~/.orcli under the alias current.

List API Keys

orcli ls

List saved API keys, their aliases, and which key you're currently using.

{
    current: "alef-ajbsd-9713ni-ajk1",
    salesforce: "alef-ajbsd-9713ni-ajk1",
    blog: "1p03-11827-134713-anfe"
}

Forget API Keys

orcli rm [name]

Deletes an API key from ~/.orcli.

orcli rm blog
# {
#   message: "forgot key 'blog'.",
#   ok: true
# }

If name is *, it will delete all saved keys:

orcli rm *
# {
#   message: "forgot all keys.",
#   ok: true
# }

If you attempt to remove a key that does not exist, orcli will report an error:

orcli rm *
# {
#   message: "forgot all keys.",
#   ok: true
# }

Get an item

orcli get [collection] [key]

Retrieve an item by collection and key, like this:

orcli get users garbados
# { "name": "Diana Thayer" }

List collection contents

To list the items in a collection, just get it:

orcli get users --start=garbados

Create an item

orcli post [collection]

Creates a new item with an auto-generated key. Passed attributes become the item's attributes, like so:

orcli post items --name="a superb vase" --cost="two high fives"

Upsert an item

orcli put [collection] [key]

Creates a new version of the item in the given collectio at the given key, using any passed attributes as attributes of the new item version. For example:

orcli put users garbados --name="Diana Thayer"

... creates this:

{
    name: "Diana Thayer"
}

Delete an item

orcli del [collection] [key]
orcli delete [collection] [key]

Deletes a given item. Remember that to actually delete something, you'll need to pass the purge flag:

orcli del users garbados --purge=true

Delete a collection

orcli del [collection]
orcli delete [collection]

Delete a collection and all its contents. Requires the --force flag to actually delete the collection, like so:

orcli del users --force=true

Partial Updates

orcli patch [collection] [key] [operation] [path] [value/from] [--if-match]

Performs a partial update on a given item. The operations available are listed in the Orchestrate docs.

# rename the 'name' field to 'alias'
orcli patch users garbados move alias name
# add the field 'can_jump_high' and sets it to 'false'
orcli patch users garbados add can_jump_high false

You can also feed multiple operations like this:

cat patch.json | orcli patch users garbados

The JSON body fed to Orcli is used as the request body of the patch request.

Passing the --if-match flag will only perform partial updates if the given ref value is the same as in the latest item version. For example:

cat patch.json | orcli patch users garbados --if-match cbb48f9464612f20

This can help you ensure you're working with the latest version of an item, and not overwriting anyone else's changes.

Merge Updates

orcli merge [collection] [key] [...values] [--if-match]

Merges the given values into the given item, leaving unmentioned fields unmodified.

orcli merge users garbados --name="Diana Agrotera Thayer"

Flags:

• --if-match [ref]: Updates the item if the given ref matches the item's latest ref.

Search

orcli search [collection] [query]

Performs a search query, like this:

orcli search users "name:Diana* username:gar*" --sort=value.created_at --aggregate=value.babeness:stats

The query parameter is a Lucene search query. For information on syntax, check the docs.

Flags:

• --sort: Sorts search results, as detailed in the docs.
• --aggregate: Aggregates information about search results, as detailed in the docs.

Get relations

orcli graph [collection] [key] [...relations]

Retrieves (by default), creates, or deletes relationships between objects.

# retrieve all your friends' likes
orcli graph users garbados friends likes

Create relations

orcli graph [from_collection] [from_key] [...relations] create [to_collection] [to_key]

Creates all given relations from the first item to the second.

Delete relations

orcli graph [from_collection] [from_key] [...relations] delete [to_collection] [to_key]

Deletes all given relations from the first item to the second.

List events

orcli event [collection] [key] [type]

List events.

Flags:

• --start [timestamp]: Returns only events after the given timestamp, inclusively.
• --end [timestamp]: Returns only events before the given timestamp, inclusively.
• --after [timestamp]: Returns only events after the given timestamp, non-inclusively.
• --before [timestamp]: Returns only events before the given timestamp, non-inclusively.

Orchestrate supports a bunch of date time formats so you can do silly stuff like this:

orcli event users garbados timeline \
--before=`date` \
--after=`date -v1988y -v8m -v16d -v0S -v0M -v0H`

This will return every timeline event for garbados before whenever you ran the command, and after August 16, 1988, since date returns a valid date format by default.

Get an event

orcli event [collection] [key] [type] [timestamp] [ordinal]
orcli event users garbados timeline 1739058730 1

Retrieves the given event.

Create an event

orcli event [collection] [key] [type] create (timestamp) [...values]
orcli event users garbados timeline create --type=status --text="that butt though"

Creates a new event with the given values. Orchestrate will generate a timestamp for the event unless you pass one explicitly, like so:

orcli event users garbados timeline create "Aug 16 1988" --born=true

Update an event

orcli event [collection] [key] update [timestamp] [ordinal] (ref) [...values]

Overwrites the given event with new values. Pass a ref value if you want to update the event only if the given ref matches the event's latest one.

Flags:

• --if-match [ref]: Updates the event if the given ref matches the event's latest ref.

Delete an event

orcli event [collection] [key] delete [timestamp] [ordinal]

Deletes the given event.

Flags:

• --if-match [ref]: Deletes the event if the given ref matches the event's latest ref.

List item refs

orcli refs [collection] [key]

Lists an item's ref history.

Tests

To run orcli's test suite, just follow these steps:

git clone https://github.com/orchestrate-io/orcli.git
cd orcli
npm install
npm test

License

ASLv2, yo.