ashare-cli
v0.2.2
Published
Publish HTML and Markdown to ashare.net from the terminal and share it with your company, specific emails or a password; collect comments
Maintainers
Readme
ashare CLI
Publish HTML and Markdown documents to ashare.net from the terminal, share them only with the right people (your company, specific emails or a password) and work with the comments readers leave on them. For scripts, CI and agents that run shell commands but have no MCP. A thin wrapper over the ashare REST API: no logic of its own, no dependencies, Node.js 20 or newer.
npx ashare-cli login
npx ashare-cli publish report.htmlInstall
npm install -g ashare-cli # gives you the ashare commandOr run any command through npx ashare-cli … without installing. The examples below use ashare.
Sign in
Sign in at ashare.net/login with your email (a 6-digit code comes by mail, no password) and create a key on ashare.net/me/api. Then:
ashare login # asks for the key
echo "$KEY" | ashare login # reads it from stdin
ashare login --key <key> # stays in your shell history, prefer the two abovelogin checks the key against the server and saves it to ~/.config/ashare/credentials.json ($XDG_CONFIG_HOME/ashare if set), readable by you only. ASHARE_API_KEY in the environment wins over the saved key: in CI set the variable and skip login.
Another server, for example a local one: --base-url <url> on any command, or ASHARE_BASE_URL, or ashare login --base-url <url> to save it next to the key. Default: https://ashare.net.
Publish and update
ashare publish report.html
ashare publish notes.md --title "Q3 notes" --visibility public --expires 7d
ashare publish report.html --password s3cret
ashare publish site/ # a folder: index.html with its CSS, images and pages
ashare publish site.zip
ashare publish plan.md --visibility company # you, the people you share with and your organizationThe format comes from the extension: .html/.htm, .md/.markdown, .zip. Anything else needs --format html|md|zip. A folder goes as a site of several files: the CLI zips it with the zip tool, which macOS and most Linux systems have; without it, zip the folder yourself and publish the .zip. index.html must sit at the top of the folder or archive.
A new document is private: only you can open it until you let people in with ashare share <id> <email> or open it with --visibility public. --visibility company opens it to your organization on ashare as well: its members and anyone who signs in with an email on its domains. Create the organization on ashare.net/me/settings first; without one the server refuses company and nothing is published. Your defaults from ashare.net/me/settings apply when you pass neither --visibility nor --expires.
ashare update <id> report.html --base-version 1 # a new version at the same link
ashare edit <id> --old "100 USD" --new "200 USD" --base-version 2
ashare get <id> # the source of the current version
ashare get <id> --version 1 -o v1.html
ashare update <id> site/ --base-version 3 # a site: the whole folder again, not only the changed file--base-version is the version you last read: if someone published a newer one since, the server refuses with a conflict and nothing is overwritten. edit replaces one fragment that occurs exactly once in the current version; --new "" deletes it. In a site of several files get and edit work on index.html, and edit keeps the other files.
To show what changed, open https://ashare.net/a/<id>?v=3&diff=2: version 3 with the changes since version 2 highlighted.
Comments
ashare comments <id> # open threads: the quoted text, the comment, the replies
ashare comments <id> --all # resolved ones too
ashare reply <id> <thread> "Fixed in v3"
ashare resolve <id> <thread>
ashare reopen <id> <thread>Replies go out as “agent”.
Who can open it
ashare share <id> [email protected] [email protected] # add to the list of a private or company document
ashare share <id> [email protected] --replace # the list becomes exactly these
ashare protect <id> # show the current settings
ashare protect <id> --visibility public # public, private or company
ashare protect <id> --expires 30d --password s3cret
ashare protect <id> --expires "" --remove-password
ashare protect <id> --notify off # on, off, or default (as in your account settings)
ashare requests <id> # people who asked to open a private or company document
ashare requests <id> --all # the approved and denied too
ashare approve <id> <request> # adds them to the list and emails them the link
ashare deny <id> <request> # sends them nothing
ashare views <id> # who opened it: signed-in readers, how often, last and first timeviews lists the signed-in readers of a private or company document, the latest first. You are not counted. Readers of a public link and readers who did not sign in only add to the view count in ashare list.
Embed on other sites
ashare protect <id> --embed https://www.notion.so,https://example.com # these sites may show it in an iframe
ashare protect <id> --embed '*' # any site
ashare protect <id> --embed none # ashare.net only
ashare protect <id> --embed default # as in your account settingsBy default a document shows in a frame only on ashare.net, or on the sites you set for all your documents on ashare.net/me/settings. --embed gives one document a list of its own: origins like https://www.notion.so, no path, up to 20. The embed code is <iframe src="https://ashare.net/a/<id>"></iframe>. Embed public documents without a password: a reader inside someone else's site cannot sign in or enter a password.
Hide the version history
ashare publish report.html --hide-history # readers see only the current version from the start
ashare protect <id> --hide-history # later
ashare protect <id> --show-history # back to every versionWith the history hidden, readers see only the current version: no version number, no list of versions, no comparison, no comments left on older versions, and old links like ?v=1 answer “not found”. You, signed in on ashare.net, still see and compare every version; get --version and update work as before. protect and publish print “history hidden from readers” while it is on.
The rest
ashare list # your documents: id, version, views, title, link, marks
ashare open <id> # print the link and open it in the browser
ashare delete <id> # with all versions and comments, no undo
ashare --helpScripts
--json on any command prints the API response as is, for jq. get --json prints the metadata with the list of versions instead of the source.
URL=$(ashare publish report.html --visibility public --json | jq -r .url)
ashare comments "$ID" --json | jq -r '.[].body'Exit codes: 0 done, 1 the server or the network said no (the error goes to stderr), 2 wrong arguments. On 401 the CLI suggests ashare login.
Development
From the root of the repository:
npm run cli:build # cli/dist/ashare.js, one file, esbuild
npm run cli:test # unit tests
node cli/dist/ashare.js --help
npx ./cli publish report.html # the local build through npx
cd cli && npm pack # the tarball npm would publish; prepack builds itThe source is cli/src/ashare.ts, the entry point cli/src/main.ts. Integration tests run the built file against a server: the == cli section of scripts/smoke.sh.
