# Cosmic CLI

This is the official command line tool for Cosmic (opens new window). Use it to log in to your Cosmic account, manage Buckets, data, files and users within your Buckets, all from the comfort of your command line interface.

Quick Tip

For a quick reference to get content from your Bucket, click the "Developer Tools" button found on select pages in your Bucket Dashboard (opens new window).

# Installation

Install the CLI globally:

npm i -g cosmic-cli

To check that it installed properly, run cosmic on your command line and you should see a list of commands.

# Getting Started

Let's walk through the commands you need to get started. For an introduction to the Cosmic CLI run the begin command.

cosmic begin

# Login

Use your credentials (from https://cosmicjs.com) to login on the command line. You will only have to do this once. If you used GitHub to sign up, you can also login via authentication token which you can find at https://cosmicjs.com/account/authentication

$ cosmic login
  ? Email: starman@gmail.com
  ? Password: [hidden]

# Usage

All Cosmic CLI commands are of the format:

cosmic [command] [options]

# Use Bucket

Now that you are logged in, you can connect to any of your Buckets on your account. The use-bucket command will set your Bucket config options. You can set your read and write access keys with this command for later use to interact with your Bucket content. Find your Bucket slug, read_key, and write_key access keys in Your Bucket > Settings > API Access after logging into your account (opens new window).

$ cosmic use-bucket simple-react-blog --read_key your-read-key --write_key your-write-key
Now using bucket simple-react-blog

To test that we connected to the Bucket properly:

$ cosmic get-objects --limit 1
{ objects:
   [ { _id: '59df6dd5fd8d731b2100118d',
       bucket: '59df6dcbfd8d731b21001188',
       slug: 'jane-doe',
       title: 'Jane Doe',
       content: '<p>Something about Jane...</p>',
       metafields: [Array],
       type_slug: 'authors',
       created: '2017-10-12T13:27:49.663Z',
       created_at: '2017-10-12T13:27:49.663Z',
       status: 'published',
       metadata: [Object] } ],
  limit: 1 }

Now you are ready to use any of the commands to have full control over your Bucket!

# Help

Run cosmic -h for a list of all commands. The list is also included at the bottom of this README (opens new window).

Run cosmic [command] -h for details on options for a specific command.

# Examples

Below are a few examples of commands. Only a handful of the possible options are shown for the commands.

Creating an Object Type and then an Object

Creating a "Planets" Object Type and specifying default Metafields all Objects in this Object Type should have. For this example all planets will now include the Metafield titled "Radius". See the REST API docs for all Metafield options.

$ cosmic add-object-type --slug planets --title Planets --metafields '[{"title": "Radius","type":"text", "key": "radius"}]'

Making an edit to the Object Type. This example adds another Metafield to the "Planets" Object Type.

$ cosmic edit-object-type -s planets --metafields '[{"title": "Radius","type":"text", "key": "radius"},{"title": "Distance from Sun","type":"text", "key": "distance_from_sun"}]'

Creating an Object in the "Planets" Object Type:

$ cosmic add-object --type_slug planets --title Venus --metafields '[{"title": "Radius","type":"text", "key": "radius", "value": "3,760 miles"},{"title": "Distance from Sun","type":"text", "key": "distance_from_sun", "value": "67.24 million miles"}]'

Uploading Files to a Bucket

We upload any file from our computer to Cosmic with the name provided to -t, and into a specified folder (optional).

Using shorthand params -f for --file and -t for --title

$ cosmic add-media -f ./my-cat.png -t my-cat.png --folder cat-images

# JSON String Inputs

Some commands allow for two types of input: argument based and json string based. This is best illustrated with an example:

To add a new barebones Object with only a title that is of Object Type planets, there are two ways we could go about it, with equivalent results:

$ cosmic add-object --type_slug planets --title Venus


$ cosmic add-object --json '{"type_slug": "planets", "title": "Venus"}'

The json string option is convenient in some use cases, and is included on the following commands:

  • add-object
  • add-object-type
  • edit-object
  • edit-object-type

# Commands

For a list of the options for a command, use cosmic [command] -h

  • begin Guide to Getting Started
  • login
  • which-user outputs the email of the current user
  • which-bucket outputs the slug of the current Bucket
  • which-app outputs the slug of the current app
  • get-buckets [options] shows Buckets available to user
  • install-app installs an app to your bucket and downloads the repo to your machine
  • deploy-app [options] deploys an app to the Cosmic App Server
  • view-app Opens browser window with demo link
  • browse-apps [options] search for apps or see all
  • start-app starts a downloaded app on your machine
  • get-bucket [options] get current bucket object
  • use-bucket [options] [slug]
  • add-bucket [options]
  • delete-bucket [options]
  • get-objects [options]
  • get-object [options]
  • get-object-types
  • add-object-type [options]
  • edit-object-type [options]
  • delete-object-type [options]
  • add-object [options]
  • edit-object [options]
  • delete-object [options]
  • add-media [options]
  • get-media [options]
  • delete-media [options]
  • add-webhook [options]
  • delete-webhook [options]
  • add-user [options]