I needed some tools for talking to the Known API from the command line in order to play around with a few ideas I’ve been having.

So, I put together a few BASH shell scripts.


  • Install the prerequisites: curl php_cli python openssl base64
  • Check out the repository and add it to your system path.

Note, due to this bug, you’ll need to be running the latest version of Known if you want to use the syndication functionality.

Talking to Known

The first thing you’ll need (other than a Known account of course) is to get your API key, you can find this in your settings page under “Tools and Apps”.

You can then use those as parameters to known.sh. For example, to make a status update you’d type:

Of course, you might want to use one of the wrapper scripts like status.sh, which also supports syndication e.g:

If successful, the scripts will output a JSON representation of what the API says.

Have fun!

» Visit the project on Github...

I’ve submitted a pull request over on the Known project git repo that allows you to specify a CURL proxy connect string (which has since been merged).

If specified, this connection string will make all web service and web mention calls be sent via a proxy server.

This was a relatively small change, but is useful in many ways – for example, for communicating through a corporate firewall. It is also provides a way of routing Known to Known communication over TOR.

Why would you want to do this?

Well, this is part of an ongoing effort to harden Known against the new attack realities we face on the internet in the 21st century.

One of the things that the Snowden documents have revealed, is that the bad guys are particularly interested in harvesting everyone’s social graph – who knows who – so that they can, among other things, automate guilt by association.

Going to some lengths to hide this information from an attacker sitting on the wire, is therefore, a prudent thing to do.

Ok, how?

  • Install the TOR proxy on your server; this may just be as simple as typing apt-get install tor.
  • By default the tor package only installs the client, so you’ll need to modify the config to open up a SOCKS relay.
  • Next, tell your known site to use this relay; open your config.ini and set the proxy_string:


Routing over TOR is only part of the solution of course. For the communication to be properly safe, you should also encrypt the communication using HTTPS.

Unfortunately, whether a connection is conducted over encrypted HTTPS or not is largely up to your friend’s webserver. But, you wouldn’t be silly enough to run unencrypted, right?

Given the numbers of nasty attacks that can be launched against an unencrypted web connection, the internet at large is now moving towards deprecating unencrypted port 80 HTTP. Google search results will now give preferential treatment to encrypted websites, so that’s another reason!

So, don’t be part of the problem. Have fun!