diff --git a/README.md b/README.md
index ed71d7441..407f0693b 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,113 @@
-# vulcanosec cli
+# Vulcano CLI
 
-CLI tool for vulcanosec.
+Test your Server, VM, or workstation.
 
-## Development
-
-You can get a console within your evaluation context. Example:
+Small example: Write a your checks in `test.rb`:
 
 ```ruby
-rule "sth-new" do
-  binding.pry
-  ...
+describe file('/proc/cpuinfo') do
+  it { should be_file }
+end
+
+describe ssh_config do
+  its('Protocol') { should eq('2') }
 end
 ```
 
-Once you run `vulcano check myprofile/` you will get a CLI context.
+Run this file locally:
 
+```bash
+vulcano exec test.rb
+```
+
+## Installation
+
+Requires Ruby ( >1.9 ).
+
+To simply run it without installation, you must install [bundler](http://bundler.io/):
+
+```bash
+bundle install
+bundle exec bin/vulcano help
+```
+
+To install it as a gem locally, run:
+
+```bash
+gem build vulcano.gemspec
+gem install vulcano-*.gem
+```
+
+You should now be able to run:
+
+```bash
+vulcano --help
+```
+
+## Configuration
+
+Run tests against different targets:
+
+```bash
+# run test locally
+vulcano exec test.rb
+
+# run test on remote host on SSH
+vulcano exec test.rb -t ssh://user@hostname
+
+# run test on remote windows host on WinRM
+vulcano exec test.rb -t winrm://Administrator@windowshost
+
+# run test on docker container
+vulcano exec test.rb -t docker://image_id
+```
+
+## Custom resources
+
+You can easily create your own resources. Here is a custom resource for an
+application called Gordon and save it in `gordon_config.rb`:
+
+```ruby
+require 'yaml'
+
+class GordonConfig < Vulcano.resource
+  name 'gordon_config'
+
+  def initialize
+    @path = '/etc/gordon/config.yaml'
+    @config = vulcano.file(@path).content
+    @params = YAML.load(@config)
+  end
+
+  def method_missing(name)
+    @params[name.to_s]
+  end
+end
+```
+
+Include this file in your `test.rb`:
+
+```ruby
+require_relative 'gordon_config'
+```
+
+Now you can start using your new resource:
+
+```ruby
+describe gordon_config do
+  its('Version') { should eq('1.0') }
+end
+```
+
+## Contributing
+
+1. Fork it
+1. Create your feature branch (git checkout -b my-new-feature)
+1. Commit your changes (git commit -am 'Add some feature')
+1. Push to the branch (git push origin my-new-feature)
+1. Create new Pull Request
+
+
+Copyright 2015 Chef Software Inc. All rights reserved.
+Copyright 2015 Vulcano Security GmbH. All rights reserved.
 Copyright 2015 Dominik Richter. All rights reserved.
diff --git a/vulcano.gemspec b/vulcano.gemspec
index a438f5f04..9fd085b92 100644
--- a/vulcano.gemspec
+++ b/vulcano.gemspec
@@ -20,7 +20,6 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'bundler', '~> 1.5'
   spec.add_development_dependency 'minitest', '~> 5.5'
-  spec.add_development_dependency 'rspec', '~> 3.3'
   spec.add_development_dependency 'rake', '~> 10'
   spec.add_development_dependency 'pry', '~> 0.10'
   spec.add_development_dependency 'rubocop', '~> 0.33.0'