T2 CLI Spec: comments requested

Kelsey 2015-05-02 01:37:24 UTC #1

Update

All commands are now moved to GitHub issues. Any further discussion of these commands should take place on their corresponding Issues:

tessel provision: #64
tessel [-h | --help]: #65
tessel init: #76
tessel rename: #77
tessel erase: #78
tessel run: #79
tessel root: #80
tessel update: #81
tessel wifi: #82
tessel list: #86
tessel ap: #87
tessel logs: #88
tessel push: #91
tessel select: no longer a command, see #93
tessel status: #95

Original post

Spec for the T2 CLI. We've discussed it quite a bit internally (you can check out the comment history here if you're curious) but new insights are welcome.

This RFC is open until ~Monday, at which point I plan to turn this into many Github issues to implement.

CLI Commands

First things first

tessel provision

[ONLY WORKS OVER USB] creates a .tessel folder with ssh keys in your home directory and uses those ssh keys to authorize you to push code to the USB-connected Tessel

Authorized on device Tessel-0123456789ab (Rafael)

tessel [-h | --help]

Prints out all the commands and what they do (usage)

$ tessel
> Usage: tessel <command> [--help]
>  help	prints usage. Add ‘--help’ after any command for more info
>  init	initializes the current directory (package.json and blinky)
>  list	list nearby tessel devices
>  select	choose which tessel you want to interact with
>  rename	change the hostname of the selected tessel
>  erase	erase code pushed to flash
>  logs	display the console.logs from the currently running process
>  push	push a file to flash to be run anytime tessel is powered
>  root	provides access to the underlying linux system on board
>  run		run a file in RAM immediately
>  status	get the current status of the selected tessel
>  update	update the selected tessel to latest firmware build
>  ap		create a wireless access point on the selected tessel
>  wifi	configure wifi connection on the selected tessel
$

$ tessel --help
> Usage: tessel <command> [--help]
> ...
$

tessel init [directory]

Same as npm init. Creates package.json in the current working directory, or the provided directory. Also creates example index.js with blinky example code.

$ tessel init --help
> Usage: tessel init [dir] [--help]
>  dir:	initialize in the provided directory
$ 


$ tessel init
> Initializing tessel repository...
> Created package.json.
> Wrote “Hello World” to index.js.
$

For multiple tessels

tessel list

Lists all connected tessels. Shows which tessel is selected and authorization status of each tessel.

$ tessel list --help
> Lists all connected tessels. Shows which tessel is selected and authorization status of each tessel.
$ 

$ tessel list
> Searching for nearby tessels…
>  USB/LAN	Rafael [selected]
>  LAN		Bulbasaur
>  LAN          Tessel-456789abcdef
>  LAN		Mewcat (requires authorization with `tessel provision`)
>  LAN		Tessel-89abcdef0123 (requires authorization with `tessel provision`)
$

tessel select

Shows current tessel that you’ve selected. Upon selection, blink LED on tessel for 3 seconds.

$ tessel select --help
> Usage: tessel select <id | name> [--help]
>  id|name:		the id or name of the tessel to select
$ 

$ tessel select Bulbasaur
> Selected Bulbasaur (Tessel-23456789abcd) via LAN
$ 

$ tessel select Tessel-456789abcdef
> Selected Tessel-456789abcdef via LAN
$ 

$ tessel select
> Connected to Tessel-456789abcdef via LAN
$

Refers to selected tessel

tessel rename [-r | --reset]

Names the Tessel by changing the hostname of the device. Name restrictions found here: http://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_host_names

$ tessel rename
> Usage: tessel rename <name> [-r | --reset] [-f | --force] [--help]
>  name:		the name to rename the currently selected tessel
>  -r | --reset:	reset the name of the device
$ 

$ tessel rename Jigglypuff
> Changed name of device Tessel-0123456789ab to Jigglypuff
$ 

$ tessel rename Snorlax
> Changed name of device Tessel-0123456789ab from Jigglypuff to Snorlax
$ 

$ tessel rename --reset
> Reset the name of device Tessel-0123456789ab
$

tessel erase

Erases code pushed to Flash using the tessel push command

$ tessel erase --help
> Usage: tessel erase [--help]
$ 

$ tessel erase
> Erasing files from flash...
> Files erased
$

tessel logs [-n ] [-t | --tail] [stdout | stderr]

Lists the recent activity and console.logs (100 lines default) from the running program

$ tessel logs --help
> Usage: tessel logs [-n <lines>] [-t | --tail] [-o <stdout | stderr>] [--help]
>  -n:			the number of lines of log to display
>  -m|--monitor:	continuously display the logs as they are updated
>  stdout|stderr:	display the logs from the specified output stream
$ 

$ tessel logs -n 2
> Bulbasaur is running index.js
> #[03/31/2015 18:10:28] This is my logggggg
> #[03/31/2015 18:10:29] Look at it!
$ 

$ tessel logs --tail
> Bulbasaur is running index.js
> #[03/31/2015 18:10:28] This is my logggggg
> #[03/31/2015 18:10:29] Look at it!
> #[03/31/2015 18:11:29] Look at it!
> #[03/31/2015 18:12:29] Look at it!
> #[03/31/2015 18:13:29] Look at it!
> #[03/31/2015 18:14:29] Look at it!
> #[03/31/2015 18:15:29] Look at it!
> #[03/31/2015 18:16:29] Look at it!
> #[03/31/2015 18:17:29] Look at it!
> #[03/31/2015 18:18:29] Look at it!
$ 

$ tessel logs -t stderr
> Bulbasaur is running index.js
> #[03/31/2015 18:10:28] Error: index.js:146 - index out of bounds yo
$

tessel push [--lan | --usb]

Push the file/dir to Flash memory to be run anytime the Tessel is powered, runs the file immediately once the file is copied over.

$ tessel push --help
> Usage: tessel push <index.js> [--usb | --lan] [--help]
>  index.js:		the Javascript file to push to flash
>  --lan | --usb:	connect over the specified connection type
$ 

$ tessel push index.js
> Writing index.js to flash on Mewcat (16kB)...
> Pushed index.js to Mewcat
> Running index.js...
> Hello world!
$ 

$ tessel push index.js --usb
> Writing index.js to flash on Mewcat (16kB)...
> Failed to write index.js to Mewcat (no usb connection)
$

tessel run [--lan | --usb]

Run the file in RAM immediately

$ tessel run --help
> Usage: tessel run <index.js> [--lan | --usb]
>  index.js:		the Javascript file to run in RAM
>  --lan | --usb:	connect over the specified connection type
$ 

$ tessel run index.js
> Running index.js on Bulbasaur...
> Hello world!
$

tessel root [-i ]

Provides access to the underlying Linux system running on Tessel 2: exactly SSH (copies regular SSH keys to authorize and SSHes in as Linux computer)

$ tessel root --help
> Usage: tessel root [-i <path>] [--help]
>  -i <path>:	provide a path to the desired ssh key
$ 

$ tessel root
> Accessing root...
root@192.168.128.124 #

tessel status

Prints name of the tessel and information about connection and running scripts

$ tessel status --help
> Prints name of the tessel and information about connection and running scripts
$ 

$ tessel status
> Name:	Bulbasaur
> Ident:	Tessel-23456789abcd
> IP:		192.168.2.5
> Script:	index.js in RAM (16MB) started 03/31/2015 18:10:28
$ 


$ tessel status
> Name:	Rafael
> Ident:	Tessel-0123456789ab
> IP:		192.168.4.2
> USB: 	/dev/tty.usbmodem1422
> Script:	no script running
$

tessel update [-l | --list] [-b | --build] [-f | --force]

Updates tessel to most recent build if it’s not already on that build, displays info including when tessel was last updated, when build was published

$ tessel update --help
> Usage: tessel update [-l | --list] [-b | --build]
>  -l | --list:	show the last five builds and current build
>  -b | --build:	update to a specific build
>  -f | --force:	force tessel to update to the specified version
$ 

$ tessel update
> New firmware version found...
> Updating Bulbasaur to latest build...
> Updated Bulbasaur from v0.3.12 to v0.3.14
$ tessel update
> Bulbasaur is already on the latest firmware build. You can force an update with “tessel update --force”
$ 

$ tessel update -b
> Usage: tessel update -b <build_number>
> Example: “tessel update -b 0.3.12”
> tessel update -b 0.3.12
> Updating Bulbasaur to v0.3.12...
> Updated Bulbasaur to v0.3.12
$ 

$ tessel update -l
> Latest builds:
>  v0.3.14 Published 04/1/2015 03:35:57
>  v0.3.13
>  v0.3.12 Bulbasaur last updated 03/31/2015 08:22:03
>  v0.3.11
>  v0.3.10
>  v0.3.09
$ tessel update
> New firmware version found...
> Updating Bulbasaur to latest build...
> Updated Bulbasaur from v0.3.12 to v0.3.14
$ tessel update -l
> Latest builds:
>  v0.3.14 Bulbasaur last updated 03/31/2015 08:22:03 to latest firmware
>  v0.3.13
>  v0.3.12 
>  v0.3.11
>  v0.3.10
>  v0.3.09
$

tessel ap [-n ] [-p ] [-s ] [on|off]

Creates a wireless access point

$ tessel ap
> Usage: tessel ap [-n <ssid>] [-p <pass>] [-s <security>] [on|off]
>  -n <ssid>:      name of the network
>  -p <pass>:      password to access network
>  -s <security>:  encryption to use on network (i.e. WEP, WPA, PSK)
>  on:             bring up an access point that’s turned off
>  off:            turn off the access point
$

$ tessel ap -n test-network
> Created access point “test-network”
$ 

$ tessel ap off
> Turned off access point “test-network”
$ 

$ tessel ap -n test-network -p secret
> Created password protected access point “test-network”
$ 

$ tessel ap -n test-network -p secret -s WPA
> Created password protected access point “test-network” secured with WPA
$ 

$ tessel ap off
> Turned off access point “test-network”
$ tessel ap on
> Turned on access point “test-network”
$

tessel wifi

Show connection status, IP address, signal strength, bitrate

$ tessel wifi
> Usage: tessel wifi [-n <ssid>] [-p <pass>] [-s <security>] [--off] [-t]
>  -l:			show connection status and list available networks
>  -n <ssid>:	name of the network to connect with
>  -p <pass>:	password to access network
>  -s <security>:	security protocol to connect with (i.e. WEP, WPA, PSK)
>  -t:			attempt to connect for the provided number of seconds
>  --off:		disconnect from a wifi connection
$ 

$ tessel wifi -n test-network
> Connecting to network “test-network”...
> Connected to network “test-network”
$ 

$ tessel wifi -n test-network -p super-secret
> Connecting to network “test-network”...
> Failed to connect to “test-network” (ssid or password incorrect)
$ tessel wifi -n test-network -p secret
> Connecting to network “test-network”...
> Connected to network “test-network”
$ 

$ tessel wifi -n test-network -p secret -s WPA
> Connecting to network “test-network”...
> Connected to network “test-network”
$ 

$ tessel wifi -n test-network -t 1
> Connecting to network “test-network”...
> Failed to connect to “test-network” (timeout)
$

$ tessel wifi --list
> Currently connected to “test-network”
> Scanning for wifi connections...
>  technicallyWifi (67/75)
>  test-network (65/75) [connected]
>  Gaumenkitzel (33/75)
$

Additional contributors to this spec: @nplus11 @jon @kevin @tcr

jon 2015-05-02 01:45:01 UTC #2

I suggest that the tessel logs command report the last 100 lines of logs just as Heroku does.

kevin 2015-05-02 02:11:21 UTC #3

What would the semantics of tessel select be across multiple terminals or shell scripts? How would this be implemented?

If it writes the selected device to a config file, that will be shared across all the user's sessions and lead to a terrible mess of race conditions and unexpected changes.

Ideally, it would be local to the shell running the command and descendants, like an environment variable, but that doesn't work with the proposed interface without major hackery. (Making the user source a setup script, and making tessel actually a shell function, not a binary on $PATH)

Or, what's wrong with the logical extension of the current interface:

export TESSEL=Bulbasaur
tessel run ...

Can't blink it automatically, but it's at least very clear what the semantics will be.

kevin 2015-05-02 02:20:44 UTC #4

How do commands that operate on multiple Tessels deal with devices that are found via mDNS, but the user isn't authenticated on. Does it try logging into all of them to determine this? Are unauthenticated devices hidden, shown with a warning, or a fatal error?

push --all with the only granularity being "all reachable devices on the network" seems a little weird. "All the devices that are supposed to have this code", determined by a config file or something seems more reasonable.

Kelsey 2015-05-03 00:16:47 UTC #5

tessel ap is unintuitive. How about tessel router or tessel hotspot? @jon suggested access-point but that seems pretty verbose if we can avoid it

ekolker 2015-05-03 18:20:17 UTC #6

`status`

In addition to how long the existing code has been running, it might be nice to show system uptime.
It might also be cool if it told you what USB devices were connected, as well as if a connection exists over LAN. (The elephant in the room is obviously modules. Sadly, it's not possible to ID them automatically at this time.)
Memory usage may not be that useful of a statistic, frankly. IIRC, the JS runtime will grab a bunch of memory at first, then climb steadily until it has allocated almost everything, and enter an endless cycle where it garbage collects down, climbs back to ~full usage, garbage collects down, etc.. Point being, it'll consistently be a high number, and one that likely won't be correlated with "how hard the Tessel is working" (or whatever it is the desired information is here).

`-ap`

As usual, I'd like to argue in favor of not shying away from jargon simply because it's possibly new to the user. tessel ap makes sense if you know what it stands for, and if you don't, you should probably run -h anyway to figure it out. I also see no reason we couldn't have the short and long form of the command (-ap and --access-point).

I associate hotspots with coffee shops and airports (and always with access to the internet at large, which may not be the case here), and router is, in my mind, too ambiguous of a term.

dan 2015-05-03 18:39:55 UTC #7

I will put in my two cent by the point of view: "Market Communication" ... what I mean is about what you are selling the Tessel feature like ? For e.g. the case it is a Tessel Sation ... it could be "tessel station" and be a superset of sum up some more configuration options as pre configured. So the question about how to name the param is more the common question of what is simple right. My feeling is "access-point" or "accass-point-mode" ... but names as "hotspot" are only right if you are talking about definitive decision about that sounding customer feature. "router" feels not so good like "router-mode". I think the strategy of shorthands over well formed long namings would be the best way.

dan 2015-05-03 18:50:57 UTC #8

I like @ekolkers explaining about what JS does ... I think it would be a very important point to give your customers QM the option of reporting management a detailed profiling of possible memory leaks for deciding to spend money for buying more T2s... (it is cheaper than a service technician is driving 100 miles to reset a frozen unit ...)
It is about the major prejudice of JS what I have to fight for while defending my paper ...

Also it is an interesting feature for people like to create microcontroller related optimizations for transforming code (e.g. minify, remove double modules ... ). They could see very fast what it does in memory. So the output should be generated as JSON to work with in profiling environments.
That doesn't mean a special one. I think the best would be to write a own one ... for microcontrollers and use cases ... but this is another story

jon 2015-05-04 18:04:54 UTC #9

@kevin, We hadn't been considering shell scripting a common use case when drafting the initial spec of the CLI.

I don't see an issue with exporting an environment variable with the name of the Tessel has a problem for people who have multiple. Especially if the CLI also provides --name and --ip flags for every command so it's relatively easy to make one-time interactions with a Tessel.

jon 2015-05-04 18:08:20 UTC #10

@kevin the CLI attempts to log in to every device found via MDNS and reports those that have success. You can pass the -a flag to see unauthorized devices as well.

I agree that pushing to all devices in a network is a slim use case and likely to confuse more users than it provides convenience to. I recommend removing that flag. Thoughts @nplus11 @Kelsey @tcr?

jon 2015-05-04 18:14:02 UTC #11

I'm inclined to agree with Eric here for two reasons. The first is that I think access point mode is probably more of a power user feature and they are more likely to understand ap. The second is that precisely because this type of functionality has so many different names, users are likely to look it up with --help.

I agree with Dan here. In the long run, short names may require a one time look up but are generally easier to remember and faster to type.

jon 2015-05-04 18:24:40 UTC #12

I believe we already have it spec'ed out to tell you if a connection exists over LAN (via the IP Address).

I'm interested in this feature because I'd like to know roughly the peak usage so I know if I can continue writing code and how much breathing room I have. Based on your description, it sounds like that could be possible. I'm not sure if there exists a system utility that can report peak usage though.

My biggest issue with the status command is the flags. The -s flag doesn't seem to do anything different than tessel status except print out the logs which you can already do with the logs command. The -c flag seems to just give you the same info as tessel wifi -l would which isn't actually spec'ed out (@nplus11 can you add that?). I suggest we remove the flags from tessel status.

Kelsey 2015-05-04 18:45:07 UTC #13

I recommend removing that flag.

Yeah, removing the -a flag seems reasonable.

Kelsey 2015-05-04 18:50:49 UTC #14

The Tessel list command currently show: Hostname Connection Hostname. There is no reason to show the hostname twice, and the current example is false. I propose we change this to:

$ tessel list
> Searching for authorized nearby tessels…
>  USB/LAN Rafael [selected]
>  LAN     Bulbasaur
>  LAN     Tessel-456789abcdef
$

nplus11 2015-05-04 18:52:09 UTC #15

I don't think pushing to all devices is a slim use case; especially to those with tessel at a production level.

Removal of -a means super users will have to individually update devices, or write a script that does this for them. This might slightly reduce confusion to new users (assuming they even try to use tessel push index.js -a), but I think removal is more of a hindrance.

jon 2015-05-04 18:58:28 UTC #16

@nplus11, I think the only use case is going to production. I also think that it's likely that people at that stage won't want to deploy to every detected Tessel on the network. What if they have different functionalities for different Tessels? It seems like this feature isn't thought out enough to go into the spec and probably won't be useful for a long time.

I think it's more likely that people who are at this stage would be better off writing their own deployment script that fits their use cases (using the cli as a module).

nplus11 2015-05-04 19:23:38 UTC #17

If you feel that strongly about it then remove it. Initially the -a was tessel provision. A whole command allowing users to determine how Tessel's get pushed to; it was a big part of our deployment story. After some discussion it was changed to tessel push -a to make it easy to understand.

Kelsey 2015-05-04 21:34:04 UTC #18

I've modified the tessel list command above:

reformatting per previous post with verbal confirmation from @nplus11
removed -a command per discussion here, now unauthorized devices will be shown by default (cc/ @nplus11 @rwaldron)

I'm considering this resolved and have moved it into a Github issue: #86

Kelsey 2015-05-04 22:06:12 UTC #19

Per this discussion, I've removed the -a flag from tessel push. It also has a -f flag; is this still needed? @nplus11

Kelsey 2015-05-04 22:28:53 UTC #20

I'll consider tessel ap resolved, then. Any further discussion of tessel ap should happen on the Github Issue