Amethyst has a query language

The search box in Amethyst accepts twenty-one structured tokens.

It is not just a text field, it's a query language. Most of those tokens compile down into real nostr filter fields before the request ever leaves your phone. from: an author, to: a note, kind: a thing, a date window, a hashtag, a phrase, a negation. Type one and it settles into a chip as your caret leaves it.

The box keeps its own hints short: the placeholder reads "npub, username, text", and the empty screen adds "Type something to search" and "The filters above narrow what is searched — they do not search on their own." The full vocabulary is below. Everything in this post is in the current release on both the Play and F-Droid builds — nothing here is flavour-locked.

Finding search

Search lives in the top bar. There is no Search tab and no Search row in the side menu: search is always the magnifier in a screen's top bar — on Home, Discover, Notifications, Messages, nearly every feed in the drawer, and the hashtag, geohash and profile screens. It can't be pinned to the bottom bar, so if you navigate by the bottom bar, look up rather than down.

It often arrives pre-filled. The magnifier opens pre-narrowed to whatever the screen was showing — a feed's kind window, the profile you were reading, the hashtag or geohash you were filtered to. Home and Discover carry over only the top-bar filter, so from there it usually opens blank. Tap it from someone's profile and you get a from: chip for that person, free.

The twenty-one tokens

Combine them freely. This is a legitimate query:

kind:article from:npub1… #bitcoin since:2026-01 -airdrop "proof of work"

from: — who wrote it. from:vitor@vitorpamplona.com · from:npub1… · from:vitor pops a picker. Accepts npub, nprofile, raw hex, a NIP-05 address, or a display name the picker resolves for you. Only an npub draws as a chip; nprofile, hex and names filter but stay plain text. A name the picker never resolved sends no query at all — choose the person from the picker and the search runs. See "When a search runs" below.

to: — what it points at. to:npub1… finds posts mentioning that person, to:note1… finds replies to and quotes of that note, to:naddr1… finds anything referencing that addressable event. Three filters behind one keyword. A to: inside a URL is deliberately left alone.

kind: — what type of thing. kind:article bitcoin · kind:30023 · kind:media from:npub1…. It takes 31 named aliases, two pseudo-kinds, or any raw kind number — 0 to 65535 draws a chip, anything larger still filters but stays plain text. Type a bare kind: and a picker lists the whole vocabulary — that picker is the in-app place to browse the aliases. kind:banana becomes a text search for the literal string "kind:banana".

The 31 aliases, so you have them to hand: note · article · channel · live · community · wiki · classified · highlight · poll · picture · video · nsite · napplet · emoji · badge · git · nest · app · workout · music · playlist · podcast · episode · software · followpack · zappoll · stories · short · longvideo · calendar · calendarset.

The two pseudo-kinds, reply and media, are client-side post-filters — they ask the relay for nothing and trim results after they arrive. reply means a kind-1 note with an e tag; media means a kind-1 note with an imeta tag or an image or video URL in the body. Both therefore only ever narrow plain text notes, so kind:media does not return picture-kind posts — picture is its own alias in the list above.

since: and until: — a date window. since:2026-01-01 nostr · since:2025 until:2026-03. Three spellings each: YYYY, YYYY-MM, YYYY-MM-DD. A partial date names a whole span in your own timezone, so until:2026 includes all of December. Repeating a bound narrows rather than replaces, so a window can only shrink. Only the full YYYY-MM-DD spelling draws a chip; a calendar sits under the field while the date is unfinished and leaves once you've typed a whole day. A year or a year-month filters all the same — it just doesn't draw a chip.

#hashtag. #bitcoin lightning · #nostr kind:article. It does more work than it looks: one #tag fans out into three separate questions in the same request — the tag on the event itself, the tag used as a NIP-32 label, and the NIP-73 external-id form on comments written about the topic. The first two are asked in three casings — bitcoin, Bitcoin, BITCOIN — because clients disagree about hashtag case; the comment form is asked as #bitcoin and bitcoin. A # inside a URL fragment is not a tag.

label: — NIP-32 marks. label:review/app · label:en. This queries label events, not the things they label, because the mark lives on the label. You get the labels back, not the labelled content — think of it as a curation-inspection token rather than a content filter.

group: — a NIP-29 relay group. group:abc123 deploy. A bare group: pops a picker of every relay group this device has seen — joined or not. It also fetches the room's metadata separately, deliberately unconstrained by your other terms, so a result can name its room.

Tokens that search the comments about a thing

Eight tokens share one rule, and it is worth knowing before you use any of them:

site:, geo:, isbn:, doi:, isan: and podcast:* search the NIP-22 comments written ABOUT the thing, not the thing itself.

site: — comments about a web page. site:bitcoin.org/bitcoin.pdf · site:https://example.com/post. Asked in several spellings at once: https:// and https:// when you typed no scheme, with and without a trailing slash, host lowercased and path left alone. Results land among the notes.

geo: — comments about a place. geo:u4pruy. This is distinct from the geohash feed, and there is no separate geohash result list — matches appear among the notes.

isbn: — books. isbn:978-0-13-110362-7. Asked with hyphens dropped and as typed.

doi: — academic papers. doi:10.1000/182. Asked lowercased and as typed.

isan: — audiovisual works. isan:0000-0000-2CEA-0000-1-0000-0000-Y. Asked uppercased, plus the five-segment root of a full eight-segment ISAN.

podcast:guid: — one show. podcast:guid:917393e3-1b1e-5cef-ace4-edaa54e1f810.

podcast:publisher: — a publisher. podcast:publisher:6f0a8f3c…. Rewritten to podcast:publisher:guid:6f0a8f3c… and asked both ways, unless you typed the guid: segment yourself.

podcast:item:guid: — one episode. podcast:item:guid:1d44e2b7…. The three podcast prefixes are matched longest-first, so this one can never half-match podcast:guid:.

Two tokens travel inside the NIP-50 search string rather than as filter fields, which shapes what you can expect from them:

lang: — language. lang:pt · lang:pt-BR · lang:zh-Hant nostr. An ISO 639 code with an optional region, riding inside the NIP-50 search string as a relay extension — so a relay that doesn't implement it ignores it and returns unfiltered results. Anything that isn't a valid code draws no chip but is still sent as a language filter: lang:banana goes to the relay as a language filter for "banana".

domain: — the host of the author's NIP-05. domain:nostrplebs.com · domain:vitorpamplona.com bitcoin. Same model: a NIP-50 extension, so relay support varies. Only a bare hostname draws a chip, because a scheme or a path belongs to site: — but like lang:, the unchipped spelling is still sent as a domain filter, and still pins your scope to Notes.

And three that shape the text rather than the filter:

-exclude — negation. bitcoin -airdrop · nostr -spam -giveaway. NIP-50 has no negation, so this happens on your device after the results arrive. The relay still sends you the posts you excluded; they just never render, and they still count against the page limit. -#tag is deliberately left alone, so you can't turn "the bitcoin hashtag" into "not the word #bitcoin" by accident.

"quoted phrase". "proof of work" · from:npub1… "lightning network". Passed to the relay verbatim; how a phrase is honoured is the relay's business. An unterminated quote is read to the end of the box, so the chip always covers exactly what the filter does.

a OR b — alternation. bitcoin OR lightning · nostr OR nips OR relays. Capped at three terms — a fourth term is dropped, because relays don't rank a longer alternation usefully. OR must be uppercase, and an orphaned OR with nothing on one side is just the word "OR". Keep it to three.

When a search runs, how scope works, and what the spinner shows

"Type something to search" after you've typed. A query needs at least one of: free text, a resolved author, a tag, or a date bound. With none of those, no request is sent at all. A bare kind:article is one such query; so is a from:vitor the picker never resolved. Add a word, a person, a tag or a date and it runs.

The All and People scope buttons. The moment your box holds any structured token, the query is pinned to Notes and the other two buttons grey out; delete the last chip and your earlier choice comes back. Scope changes what is displayed — both sub-queries are always sent, so picking "People" still pulls notes off relays.

The spinner is a button. While a search runs, a spinner sits next to the X in the text field. Tap it and a dropdown tells you which relays have answered and which are still outstanding. It stops reporting outstanding relays after twelve seconds.

The Filters sheet

At the far right of the scope row sits a small tune/slider icon. It opens a bottom sheet called Filters — well worth a tap. A coloured dot appears on the icon when anything inside is non-default.

• Source: Local or Relays. Default Relays. "Local" searches only this device's cache. It doesn't reduce what you see, because every result list scans the cache regardless, and the from:/to: picker still queries relays on its own ungated query.
• Follows only. Default off. It applies to 2 of the 7 result lists: People and Notes obey it; hashtags, relays, public chats, ephemeral chats and live activities are not affected. The relay request is sent unnarrowed — everyone comes back and the trim happens on your phone. It reads your kind-3 contact list; NIP-51 follow sets aren't included.
• Sort by: Relevance, Newest, Popular. Default Newest. Popular is highest zap total then recency. Relevance falls back to Newest when there's no free text left, so a chips-only query sorts by Newest. The section hides when scope is People, and sorting only ever applies to notes.
• Reset resets Source, Follows-only and Sort. It does not reset the scope row and does not clear your text — and clearing the box with the X leaves all four settings exactly as they were.

One more while you're here: search works against relays implementing NIP-50, and the list lives at Settings → Relays → Search Relays. One thing post eight, on relays, spells out — an empty list there is honoured as "nowhere", not replaced with defaults.

Content in the feed: what Home fetches

Settings → Home → "Content in the feed" is twenty-five per-kind switches, and they are all ON out of the box. Text notes, reposts, comments and replies, pictures, videos, shorts, articles, wiki pages, highlights, polls, classifieds, torrents, voice messages, live activities, ephemeral chats, interactive stories, chess games, bird sightings, attestations, NIP drafts, music, podcasts, fundraisers, ratings and reviews — and, since v1.17.0, Event RSVPs.

That all-on default is why a stock Home feed shows every kind at once. The important part: this is a relay bandwidth control, not a display filter. Switching one off doesn't hide those events, it drops them from the Home subscription — they are never requested at all. If Home feels heavy on a metered connection, this is the lever, and post eight, on relays, shows what it does to the fan-out. Stored per account on this phone — it does not follow you to another device.

While you're there: Home is a three-tab pager — New Threads, Conversations, Everything — and Everything ships off. Turn it on under "Visible tabs" on the same screen — which, unlike the switches above it, applies to every account on the phone.

Who's going: RSVPs on Home, and the "Friends going" lens

That twenty-fifth switch puts friends' plans in your feed. When someone in your Home list answers "Going" to a calendar event, the RSVP shows on Home as a normal post (since v1.17.0): their header and comment, then a quote frame with a tinted Going strip — "in N days" when it starts within a week. Tap the frame to open the event. Only "Going" travels this way; Maybe and can't-go never reach Home. Only each person's latest answer counts, so a later "can't go" takes the card down. There is no upcoming check, so an RSVP to last month's event shows too. "Your Home list" is whichever list Home is set to, All Follows by default. To stop fetching them, switch off Event RSVPs — go in through Home; searching Settings for "rsvp" leads to Calendar reminders.

The Calendars screen reads the same answers the other way round. Its lens row has a second chip, "Friends going" — after Feed, before Month, Week and Day — listing upcoming events that people in the selected list are going to: the event card, up to six faces, "N going", soonest first. "Upcoming" means not yet ended, so a multi-day event under way still counts. The list is the Calendars screen's own top-bar picker, which starts on Global — so out of the box "friends" means everyone; pick a list to make it yours. Muted people, and events they host, are left out.

New cards in the feed

Since v1.17.0 the feed draws a lot it used to print as text. None of it needs a setting; a card appears wherever its event does.

Lists as cards. Mute lists, pins, bookmarks, relay lists, interests, follow sets, emoji packs, curation sets and most other NIP-51 lists render as a card: centred title, up to three lines of description, the first three members, Show more. People rows open the profile; hashtags open their feed. Private members are shown only to the list's author. Four kinds still render as text: community lists (10004), public-chat lists (10005), favourite follow sets (10021) and the emoji list (10030) — the first two carry encrypted content, so what prints is ciphertext.

App lists, video lists, git status. A Zapstore curation set is an App list card whose app rows open the app's detail screen. A video curation set shows "N videos" and a strip of up to eight posters that tap through to the video. A NIP-34 status event is a pill — Open, Merged, Closed, Draft — over the issue, patch or PR it answers; an "Applied" status wears the Merged pill, and the Close, Reopen and Mark merged buttons stay on the issue and patch cards.

3D objects and avatars. A Simple Nostr Object or shard is a card with a still thumbnail, its name and "N vertices · M faces". Tap it and a viewer dialog opens: one finger turns, two fingers pan and zoom, double-tap resets, and a solid object gets a lit/flat toggle top-right. The dialog fills the width at 360 dp tall and has no close button — tap outside or press back. A cyberspace avatar renders the same way; one that hasn't paid the proof of work its size demands is not drawn, and the card says so.

Region bags. A bag card ("Hidden at a place") quotes what its tags give away and offers Search for it. The search runs inside the card, on your device, no relay involved: it prices the search first, then either sweeps with a "Searched X of Y regions" bar and Stop, or refuses with "Out of reach: about N minutes of searching on this device" when it would take more than two minutes — that estimate appears only on a refusal. Scrolling the card away cancels, and a finished search keeps its result; the button doesn't return.

Prediction markets and ballots. A kind-38000 market draws a Prediction market card — status pill, title, outcomes (yes/no as green and red halves), the winner once resolved, closing time, bet limits and fee. A ballot draws as Ballot: election id, up to four question → answer rows, proof hash. Both are read-only — no bet, no odds, no vote button; Amethyst renders these, it doesn't publish them.

The compact link preview. A page with a title or description but no image used to get a plain link; now it gets a short wide card — favicon, title, two lines of description, host. Tap opens the URL; long-press opens Link Actions (Copy URL, Comments). With URL previews switched off it stays a plain link.

Teleport to a place you are not

Tap the feed name in the middle of the top bar and you get a picker with eight groups — Feeds, Relays, Hashtags, Interest Sets, Locations, Feed Algorithms, Communities, Lists — re-pointing that feed at a different audience or topic. The entries differ per screen.

The one worth the trip: "Teleport to a place…" opens a map picker. Choose a spot anywhere on earth and the feed becomes that location's feed — the local conversation somewhere you have never been. Its sibling "Around Me" does the same for wherever you actually are, and needs coarse location permission.

Teleport itself is never saved; it immediately becomes an ordinary geohash filter. But while a location feed is active, a bookmark toggle appears next to the feed name, and tapping it saves that cell as a permanent chip in the switcher. That saved list is encrypted — only you can read it — but it is a nostr event published to your relays, not a file on your phone. Nobody else learns where you saved; they can see that you keep such a list and when you last changed it. Read-only logins get a toast.

One more thing to notice on that switcher: a favourited algorithm feed whose DVM has stopped sending heartbeats gets a trailing dimmed "•". That dot is the heartbeat indicator — there is no separate legend, so it's worth remembering.

Star a follow set, get a feed

Every follow-set card (kind 30000), yours or anyone's, carries a star beside its title (since v1.17.0). Tap it and the set joins your favourite follow sets, a public NIP-51 list; tap again to remove it. From then on the set is a selectable feed in the top-bar picker above, sorted in among your own lists — on Home and on the Badges, Communities, Music, Git, Workouts, Highlights, relay-group and Podcast feeds. Starring one of your own changes nothing visible, since your own sets are already there. The star has no text label, hides on a read-only login, and only kind 30000 has one. The favourites list has no drawer row; the picker is where it lives.

Rebuild the bottom bar around one room

The bottom bar is not a fixed set of five. It's an ordered list you build yourself from roughly fifty destinations, at Settings → Bottom Navigation Bar — drag to reorder, ✕ to remove, Restore Default to return to the stock set. The stock five are Home, Messages, Wallet, Browser, Notifications. Discover and Media are not in the stock set — this is where you add them.

The good bit is one level down. Under "Chats & Groups", the four rows expand, and each room inside gets its own Add pill — so you can pin one specific public chat, one NIP-29 relay group (or the whole host relay), one Concord channel (or its whole community) or one geohash cell as its own permanent tab. Expanding "Browser", under "Apps & Web", does the same for starred web apps, nsites and napplets. The row and the pill do different things: tapping the row expands, tapping the pill pins. Two plain entries joined "Chats & Groups" in v1.17.0: Marmot Groups and Cordn Groups, each pinnable as a tab and neither pinned out of the box. Post ten, "Four ways to talk in private", covers the rooms behind them.

The "n / 5" counter is a soft hint, not a limit. Go past five and the number turns red and the icons squeeze; that is the entire consequence. There's no minimum either — remove every tab and you get "No items pinned. The bottom bar is hidden until you add at least one.", after which the app renders no bottom bar at all. Drawer-only Amethyst is a legitimate configuration. Both the bar and your side-menu layout ride along with the account, not the phone.

Since v1.17.0 the bar also stays put: every screen opened from the drawer, and every pinned tab, keeps the bottom bar — including the ones that used to lose it: nApplets, nSites, Marmot Groups, Cordn Groups, the NIP-46 signer and My Blossom data. An in-app push — a profile or chat opened from a note — still hides it.

The profile tab called "Yours"

Every profile is a pager of up to twelve tabs. Scroll right to reach Reports (NIP-56 reports about that person) and Relays — post eight, on relays, explains why that last tab is worth the swipe.

The interesting one is the third tab, labelled "Yours". It is every post YOU ever wrote that tagged the person you are looking at — notes, reposts, articles, wiki pages, highlights, zap polls, classifieds, fundraisers, torrents, music, podcasts, public messages. (Zap polls only; the newer NIP-88 polls are left out.) Your side of the shared history.

Three things to know: it is one-directional (your posts about them, never theirs about you), capped at 200, and built entirely from the local cache, so it only sees what this device already downloaded.

The name you see for someone

Wherever a name is drawn — author rows, mentions, chat headers — Amethyst picks it in a fixed order, and since v1.17.0 a petname from your own contact list is in that order: a nickname you gave them (NIP-85) → the petname in your kind-3 contact list → their profile's display name → their profile name → a short npub. A petname therefore outranks what the person calls themselves; only your nickname beats it. Only your own contact list is read. Amethyst has no editor for petnames — they arrive in a contact list written by another client — and the nickname editor leaves them alone.

About sixty feeds, briskly

The drawer has five sections, and the one called Feeds is 33 rows on its own since v1.17.0 — 32 on Android 10 and below, where "Web apps" doesn't appear. The ones worth a line each:

Pictures and video: Media (pictures plus every video kind) lives under Navigate, not Feeds · Pictures (kind 20 only) · Shorts (vertical) · Videos (long-form). Those three are distinct feeds with distinct kinds. Shorts is a scrolling list rather than a TikTok-style pager.

Reading and writing: Reads (long-form) · Highlights · Polls · Badges · Calendars, with a second adjacent Calendar lists row for collections.

Live and audio: Live Streams, where ended streams sink but don't disappear · Nests audio rooms, which can show fewer rooms than exist — post nine, on the far corners, explains why · Podcasts and Episodes · Music and Playlists, on experimental kinds with few publishers so far.

People and places: Follow Packs, a global directory out of the box · Communities, which starts on your follows instead · Public Chats · Relay Groups · Concord Channels · Marmot Groups and Cordn Groups, new in v1.17.0 and explained in post ten, "Four ways to talk in private" · Location Channels, the geohash chat — while the geohash feed has no menu entry and is reached by tapping a location chip · Marketplace, which defaults to a location scope · and Geocaches and Cache hunts, two doors into one five-tab hub that also starts on Around Me — post twelve, "Hide something, sign it, let strangers find it".

The further end: Git Repositories, Global by default and capped at 200 · App Store, experimental kind, few publishers · Web apps, Android 11 and up only · nApplets and nSites, which keep the bottom bar since v1.17.0 (re-tapping their tab doesn't scroll to the top) · Workouts · and Emojis.

And a different section entirely. Several rows live under You rather than Feeds: Drafts · Scheduled posts, not a nostr feed but a local queue your own phone publishes from · Bookmarks, a hub holding named groups, the public/private list, Pinned Notes (this is its only menu row in the app), and bookmarked git repos and podcasts · My Lists · Hashtag Sets · Web Bookmarks · and My Emoji Packs, a different screen from the Emojis row down in Feeds. And one viewer has no drawer row in any section: the contact-list browser opens by tapping a rendered contact-list note.

And the footer. Beside the version number sits a Tor onion (since v1.17.0): coloured once Tor is fully bootstrapped, muted while it is still connecting, absent when Tor is off. Tap it and the drawer closes on Settings → Privacy Options. Post seven, on privacy and safety, has what each Tor switch covers; post eleven, "A browser that waits for Tor", has the browser side.

Discover is seven tabs — Follow Packs, Reads, Feed Algorithms, Live Streams, Communities, Marketplace, Chats — and is not on the default bottom bar. Every tab is narrowed by one shared top-bar filter, which starts on Global; if Discover looks sparse, check that filter first.

And one feed Amethyst doesn't have: there is no trending feed. Amethyst computes no hot list of its own. The nearest things are a third-party DVM algorithm, or search's "Popular" sort.

The whole thing in one breath

Search is a query language with twenty-one tokens, so start with from:, kind: and a date — and remember geo:, site:, isbn:, doi:, isan: and podcast:* find the comments about a thing, not the thing. -exclude, kind:reply and kind:media are trimmed on your phone; lang: and domain: are a request a relay may ignore; OR stops at three. Tap the tune icon for filters, and remember "Follows only" applies to the People and Notes lists. Settings → Home → Content in the feed decides what your relays are asked for — Event RSVPs included, which is how friends' "Going" answers reach Home. Lists, 3D objects, region bags, markets and ballots now draw as cards. Teleport somewhere and bookmark it; star a follow set and it becomes a feed. Pin one chat room to the bottom bar, or remove the bar entirely — and it now stays on every drawer screen. A petname outranks a display name. And the tab called "Yours" is everything you ever said about that person.

Type kind:article since:2026-01-01 into #amethyst and watch two chips appear.

nostr:naddr1qq25zmt9w358jum594kkzmn4v9kz66twv3jhsqgswaehxw309ahx7um5wghx6mmd9upzpj5fevglr36atdnzyf507s7j9z823vkttwd2n9hlnlmsflysfdutqvzqqqr4guyjuyf5