ajam / kestrel-cli

A command-line tool for staging and deploying static files.

Kestrel Command-line interface

This repository is no longer being maintained. Please use https://github.com/mhkeller/kestrel-cli2.

A command-line tool for staging and deploying static files with Kestrel Server.

Installation

npm install kestrel-cli -g

Note: You might have to run this as root user. To do that, simply begin the above command with sudo and then enter your password at the prompt.

Usage

After installation, run swoop config to get all set up.

Initialize a new project with swoop init, which will initialize git, create a GitHub repo, create a .kestrel local folder and a webhook linking this project to the Kestrel Server.

Below are the full commands and flag options. For more information about swoop config and how Kestrel works, check out the Wiki.

Usage: swoop <command>

Commands:
  config	Configure your GitHub account and server settings
  init		Git init, create GitHub repo + hooks
  deploy	Push your project to S3.
  archive	Make your current project a branch of your archive repo.
  unschedule	Clear a project's scheduled deployments.

You can also set a number of flags if you don't want to be prompted for the deploy settings.

Options:
  --help          Display help
  -e, --env       `staging` or `prod` environment.
  -m, --method    `sync` or `hard` deploy method.
  -l, --local     The local path to deploy from.
  -r, --remote    The remote path to deploy to.
  -w, --when      Time to schedule a deploy in YYYY-MM-DD HH:MM format, 24-hour clock.
  -b, --branches  <current_branch_name>:<new_branch_name> (note, this means you should avoid putting `:` in branch names)

Updating

Run:

npm update kestrel-cli -g

Like the command above, this might need to be run with sudo.

How it works

Deploying will create a commit and push it to origin master with the following structure:

<environment>::<sync-trigger>::<local-path>::<remote-path>::<when>

An example would look like:

prod::my-sync-password::my-project-folder::2014>>my-project-folder-on-s3::2015-01-01 13:00

Note: Kestrel uses : and > to encode its commands so it's best to avoid these characters in your file names.

For more information, check out the Wiki.

kestrel-cli's Issues

There's no more error feedback on duplicate git initing

Git used to throw an error if you ran git init on an existing git repository. Git 2.0 doesn't do that anymore so if you run swoop init on an existing repo it will say that everything went fine, which is accurate, but still somewhat misleading.

I don't think you can make git throw and error or warning so the better way to fix this is to change the text to something more generic like... git is on or something that makes sense for both creation and status update.

Check for swoop init on swoop deploy

It shouldn't let you deploy if you haven't swoop inited. This is a little tricky since sometimes swoop init returns errors if you've done things like already git init or created the github repo...

Make `swoop list` command to show currently scheduled jobs

So you can see what's being scheduled.

Validate all fields from within inquirer

Currently, a number of things are validated after you submit your prompts from inquirier. Inquirer also allows you to validate while you're in the prompts, though, which saves time in not having to go back and redo things based on an incorrect password or something else.

The validation still must occur after the prompts because you can bypass the prompts with flags and those values need validation.

The validation functions should be broken out into their own modules and run both in the prompts and afterward.

Ctrl-c on prompt session should exit you out completely

If you are in the middle of a prompt session and you ctrl-c, it will jump you to the end instead of exiting you out completely. This might need to be changed in http://github.com/mhkeller/config-tree.

Add update prompt if newer version is available

I could ping npm to see what is available and add a string whenever you use it

Create `swoop scrub` command to remove trigger from all commit messages

In case you want to remove all trace of your trigger from your commit messages, which as we discuss here (#2) is kinda unnecessary but it's still more secure if your trigger is unknown), you should be able to run swoop scrub to amend all those commit messages. This will have to be force pushed though, which is not good and merged if you push it so it's probably better to do on archive or something.

Really, a better strategy is to change your trigger often. This feature will be low priority since I don't like putting a force push back into the workflow.

Update docs

To reflect the new when option for publishing into the future.

More explicit branch control when pushing

Add branch as an option on swoop deploy

better detection of existing gh repo

Some more error codes on swoop deploy

If the error code is one it means you have to pull. Silence the 128 error and just say "git pull"

Schedule jobs by sub-directory

Add the local directory and remote directory as part of the job id on the cron so you can schedule more than one push on a project. Use case is for when you have multiple sub directories that might need to go different places.

Check for whether remote repo has webhook

This will add another call to the github api so it might not be good to do every time you push but it could be done through a command like swoop doctor

Indent settings printout

Store and load previous deploy settings

From the .kestrel folder

Make cli flashier

When we first made Kestrel in the halcyon days of 2014, npm init style prompts were cool beyond cool.

Now, though, we've got yeoman and bower with all sorts of colors and font styles. Kestrel is but a simple tool, yet it must remain relevant!

We're currently using promzard but we should investigate how we can add more colors to make the default values easier to read, add dropdown support for choosing things like prod vs staging environments and maybe even tab completion to make deploying to sub-directories easier.

Create .kestrel folder on `swoop init`

Handle errors somehow per #10

Print deploy flag settings on deploy

So you might copy them to easily deploy from command line without prompts

`swoop archive` should prepopulate date with last date from `.kestrel/deploy_settings.json`

Check for oustanding commits on `swoop deploy`

You won't be able to deploy if you have uncommitted changes but swoop deploy shouldn't let you put in options and then say you can't deploy.

Make a `swoop destroy`

That will delete local .kestrel folder, push with a destroy flag and remove the remote project folder in in repositories on the kestrel folder.

Make an autocomplete library for the terminal

To help autocomplete commands. Not sure if this can be done in a generic way or has to be done for bash and for zsh separately.

Add better ability to set default remote_path name as a date convention

So that in the config you could write moment style shorthand and that will be converted to the correct default path.

Update flags

The flags haven't kept up with new features. They should be made current. They are useful if you just want to redeploy and by hitting the up arrow.

Pipe git push information to stdout on swoop archive

So that people have something to look at while they wait for the push to go through.

Add more email feedback on authentication fails

Add support for deploying from arbitrary sub-dirs

In the fancy-cli branch, I'm changing the local deploy input to a list of all dirs in the current folder. This will reduce typing on currently the most typing-intensive input. If all subdirs of those dirs are included it gets potentially very long and 100% of use cases have been an "output" folder that is in the project root folder.

The best scenario would selecting from the list starts populating the text of an input field which you can then edit to whatever you want. This will require writing a custom Inquirer prompt type however.

Remove force push

When you swoop deploy it scrubs the deploy trigger from the commit message. This isn't completely necessary because of other security precautions like publish teams and push access. It also causes a git merge on the kestrel server. This second push should be removed. If you really want to scrub your commits, perhaps there is a command that will do that on archive or something like swoop clean that redoes your commits en masse.

Make a `swoop local-deploy`

In the event the server is malfunctioning, this command would:

1. Check that the working tree is clean (local is not ahead or behind of remote)
2. Push a commit notifying that it was published locally
3. S3 sync the same way as kestrel-server does

To keep the code the same from cli to server, it would be good to break that out into its own files that the cli could require.

Have `swoop init` look to existing .git folder if `swoop init`ing on existing git repo

It can take the name or parse the remote to make sure the names match.

listing sub dirs fails if no subdirs

That command should not throw an error if no subdirs exist. Perhaps putting it in a try

Don't swoop deploy if behind remote origin

Add deployed URL to `swoop deploy` success output

Better deploy feedback

When you swoop deploy the cli only knows if the push went well but can't tell you when kestrel server has successfully finished or if there was an error. I'm not sure about the best way to get these parts to talk to each other. Maybe kestrel server has a page with a websocket or something.