Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


📖 View Docs

npm version

This is the official command line tool for Cosmic. 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.

🛠️ 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 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

$ cosmic login
  ? Email:
  ? 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. To connect to the Bucket with slug 'simple-react-blog':

$ cosmic use-bucket simple-react-blog
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.

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


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


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]


The official command line tool for Cosmic



You can’t perform that action at this time.