seashells is the Python client for a shell service hosted at seashells.io

The client and the service are two repositories

The repository is small by design, and the first thing to understand is that it is only the client half of a system. The README describes it as the official client for seashells.io, and it states plainly that the server code is available in a separate repository, anishathalye/seashells-server. So the code in this tree is a command line program that talks to a service somebody else runs. That split has direct consequences for adoption. If you want to use the hosted service, this is the tool. If you want to run the service yourself, you are looking at the server repository, and this one becomes a client for an instance you operate. The top level of this repository is correspondingly thin: a src directory holding the package, a pyproject.toml, a README, a LICENSE.md and a DEVELOPMENT.md, plus the GitHub configuration and an editor configuration. There is no test directory, no examples directory and no documentation tree, which tells you the documentation lives elsewhere by choice rather than by omission.

Installation is one pip command and the help text is the manual

The package is published on PyPI, and the install step is the whole thing:

pip install seashells

The README notes that Seashells is compatible with both Python 2 and Python 3 and recommends using Python 3. The packaging metadata agrees with that, declaring requires-python as greater than or equal to 2.7 and listing classifiers for both Python 2 and Python 3. The command itself is documented by asking it:

seashells --help

That is the whole documented usage story. The README does not describe the flags, the output format or the options, it sends you to seashells.io for instructions on using Seashells and to the built-in help for the command line tool itself. There is also a launch blog post that the README links for background. For a tool whose interface is a handful of flags, this is a workable arrangement, but it does mean the package is close to self documenting and the README is a signpost rather than a manual.

Piping command output is the usage pattern the README shows

The one concrete example the README offers is a shell function that pipes both standard output and standard error into the client, and it is worth reproducing exactly because it reveals the shape of the tool. The function is credited to a linked issue comment:

    function sea() {
        $* 2>&1 | seashells
    }

So the intended interaction is that a command runs, its output is collected from both streams, and the client consumes that output on standard input. Merging the two streams with 2>&1 is the detail that matters, since a command that writes progress to standard error would otherwise lose that text. What happens next is the part the README does not spell out. The client is a client for a hosted service, and the natural assumption is that it sends the output somewhere and hands back a reference to it, but the README never says that explicitly, and the instructions it points to live on seashells.io. If the return value matters to your workflow, read the site before you script around it.

Hatchling builds it and the version lives in the package

The build configuration is a pyproject.toml with hatchling as the backend, which is a modern choice for a package whose metadata still carries Python 2 support:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

The console script is declared in the usual way, so the installed command maps to a function in the package:

[project.scripts]
seashells = "seashells.cli:main"

The version is not written in the metadata at all, it is declared dynamic and resolved from a file inside the package:

[tool.hatch.version]
path = "src/seashells/__init__.py"

[tool.hatch.envs.default]
installer = "uv"

That last entry sets uv as the installer for the default hatch environment, so the development environment is created with uv rather than pip, while the end user installation path stays the plain pip command. The metadata also carries the usual descriptive fields, with the description repeating that this is the official client for Seashells.io, the keywords shell, seashells and seashells.io, a Topic of Utilities, and an author entry for Anish Athalye.

Community clients in Node.js and Go exist but are unsupported

The README lists two other implementations, roccomuso/seashells in Node.js and hans-strudle/seashells in Go, and then adds a caveat that matters for anyone choosing between them: other clients are not officially supported. That distinction is about maintenance rather than about capability. The Python client is the one the project publishes to PyPI, badges in the README, and links from seashells.io, so it is the one whose behaviour is kept in step with the service. The Node.js and Go clients are third party efforts by their own authors, and nothing in this repository promises that they will track future changes to the service. If you are working in Python, the choice is simple. If your tooling is in another language, the alternative exists, and the difference in approach is that you are relying on someone else's compatibility work rather than on the project that owns the service.

What this README does not tell you

Three gaps are worth naming before you depend on the client. The first is the protocol and the response. There is no description of what the client sends, what the service returns, what happens when the service is unreachable, or whether the tool has a timeout or a retry. The second is configuration. The README mentions no configuration file, no environment variable and no account or authentication step, which may mean the client needs none, or may mean the details are on the website. The third is history. The repository publishes no GitHub releases, has no changelog in the top level listing, and the last push was on 2026-06-24, so there is no visible record of what changed between versions or when a change was last released to PyPI. The PyPI badge in the README is the only version signal, and it reflects the published package rather than the branch. None of this makes the client bad; it makes it small, and small means you should read seashells.io and the built-in help rather than the repository.

Running the server yourself is the other half of the story

The alternative to using the hosted service is to operate the service yourself, and the README points at the place where that is possible: the server code in the anishathalye/seashells-server repository. The difference in approach is substantial rather than incremental. With the hosted service, the client is the only thing you install and the service side is someone else's responsibility, with whatever availability and data handling terms come with it. With your own instance, you run the server, you decide where the output of your commands is stored and for how long, and you keep the client as the same thin program pointed at your instance. For an organisation that cannot send command output to a third party, that distinction is the whole decision. For everyone else, the hosted service plus this client is the smaller commitment, and the community clients exist for teams whose stack is not Python.

Editorial conclusion

Adopt the seashells client if your workflow already depends on the hosted seashells.io service and you want the official Python tool rather than one of the community clients in Node.js or Go, since it is the one the project maintains and the one whose help text and behaviour track the service. Do not adopt it if you need self hosting, because the server code is a separate repository and the client is only a client, and do not expect a documented protocol from this README, which points to seashells.io and the launch post instead. Before you rely on it, read the built-in help after installing with pip, confirm the service terms on seashells.io, and check the last push date of 2026-06-24 against your own maintenance expectations, since the repository publishes no GitHub releases.

Frequently asked questions

Official sources

1. anishathalye/seashells on GitHub
2. Issues
3. License: MIT
4. Project website
5. README