Run scripts connecting to a headless keystone instance
headstone
is a command-line tool which allows you to run scripts connecting to a truly headless keystone
instance, i.e. without routing, sessions, ...
This tool is meant for facilitating the creation of batch scripts, which manipulate mongoose documents through keystone lists.
$ npm install --global headstone
cd
to one of your keystone projects which has a models/User.js
list.
Create a javascript file:
// file: outputUsers.js
var keystone = require("keystone");
var User = keystone.list("User");
module.exports = function(done){
User.model.find().exec(function(err, users){
console.log(users);
done();
});
}
Now run headstone
passing the javascript file as a command line argument:
# outputs a list of your users
$ headstone outputUsers.js
// file: outputUser.js
var keystone = require("keystone");
var User = keystone.list("User");
module.exports = function(userId, done){
console.log("user id", userId);
User.model.findById(userId).exec(function(err, user){
console.log(user);
done();
});
}
# outputs user details for user with id 55113f1742ff1a0877242a39
$ headstone outputUser.js --userId=55113f1742ff1a0877242a39
The command line argument name must be exactly the same as the corresponding parameter name of the exported module.
// file: outputUsers.js
var keystone = require("keystone");
var User = keystone.list("User");
module.exports = function(filter, done){
User.model.find(filter).exec(function(err, users){
console.log(users);
done();
});
}
By default headstone
searches for a json
file with the same file name as your javascript file.
// file: outputUsers.json
{
"filter": {
"isAdmin": true
}
}
# outputs all administrative users
$ headstone outputUsers.js
There's a number of settings you can pass to headstone
:
-
cwd
: the directory you want to use as a current working directory. -
models
: the directory where your models are located, by default this is./models
relative to your keystone project root. -
configFile
: these settings can be stored in a file, calledheadstone.json
by default, but if you wish to choose another file name you can supply it here. -
mongoUri
: the URI of your mongo database -
mongoose
: a relative path to a mongoose module directory -
keystone
: (config file only) settings you want to pass to the keystone instance.//default { keystone:{ headless:true } }
These settings can be passed as command-line arguments, like this:
$ headstone outputUsers.js --models=./data
Or declared in headstone.json
:
// file: headstone.json
{
"models": "./data"
}
Command line arguments always trump configuration file values.
By default headstone
uses the mongoose version as declared by the keystone
module. However, if you need to use a different version you can set the mongoose option:
// file: headstone.json
{
"mongoose": "./node_modules/mongoose"
}
Uses the locally installed mongoose
version instead of the one keystone
installs by default.
headstone
automatically reads the environment declaration you've already created for your keystone project in a .env
file.
It uses the MONGO_URI
variable to connect to your mongoose database (unless overridden by a corresponding command line argument or headstone
file setting)
You can pass multiple files to headstone
they will be processed sequentially, in order.
# first outputs all users
# then outputs all posts
$ headstone outputUsers.js outputPosts.js
MIT © Camille Reynders