Home

Overview

The Apple ][ Kit, or a2kit, is a command line interface (CLI), and also a rust library, supporting disk image manipulations with language comprehension. It is designed to work with a wide variety of operating system and shell combinations.

Scope

This wiki applies to a2kit version 2.0.

Install

If you prefer to simply download an executable, visit the release page

If you want to use a package manager, you will need the rust toolchain, see rustup. Once the toolchain is installed, the CLI is installed by typing

cargo install a2kit

If you want to use a2kit as a library, edit your Cargo.toml to include a2kit under [dependencies].

Using CLI Help

The CLI's built-in help is sometimes the best reference. To get the general help

a2kit --help

To get help for a subcommand, e.g. mkdsk, use

a2kit mkdsk --help

General Principle

The CLI is intended to be used with shell pipelines. The a2kit command takes as its first argument one of several subcommands, such as get, put, tokenize, etc.. Each subcommand is designed to be serviceable either as a node in a pipeline, or as a stand-alone console interaction. As an example, if one types

a2kit get -f hello -t atok -d hello.dsk

the console will display a hex dump of the tokenized Applesoft program HELLO that is found on the disk image hello.dsk. In order to display the BASIC listing, this can be piped into the detokenize subcommand:

a2kit get -f hello -t atok -d hello.dsk | a2kit detokenize -t atok

There are many other possibilites, see the rest of the wiki pages for more examples.

Contextual Output

If output is going to the console, a2kit will produce a textual interpretation of the data, often involving hex strings. If the output is a file or another pipeline node, binary data remains binary. The textual representations of, e.g., tracks, sectors, and binary files, are intended only for console viewing.

Note on Input Redirection

If you are using a shell that supports input redirection (PowerShell does not), there is sometimes a more compact notation. For example, the following are equivalent:

a2kit get -f prog.bas | a2kit tokenize -t atxt -a 2049

a2kit tokenize -t atxt -a 2049 < prog.bas

PowerShell Caveat

PowerShell uses an object pipeline, which tends to mangle raw binary. As of this writing, native shell commands that pass raw binary, such as a2kit, have to be wrapped in a native shell. For example, from Windows PowerShell you must do this:

cmd /c 'a2kit get -f prog.bas | a2kit tokenize -t atxt -a 2049'