# Anywe CLI reference Install the Anywe command-line interface and use its implemented commands for agent development and operations. Source: https://anywe.dev/docs/tooling/cli `anywe` is the command-line executable for building, registering, testing, and operating an agent. Every command below is read from the command tree (`cli/internal/cli`); run `anywe COMMAND --help` for a command's own flags. ## Install Release `v0.3.0` is published. On macOS and Linux, install it with: ```sh curl -fsSL https://cli.anywe.dev/install.sh | sh anywe version ``` The script resolves the current version, downloads the archive for your platform, and verifies it against the published `checksums.txt` before installing; a mismatch aborts rather than installs. It writes to `~/.local/bin` unless `ANYWE_INSTALL_DIR` names another directory, and `ANYWE_VERSION=vX.Y.Z` pins a specific release. It refuses an unrecognized platform instead of guessing one, and 32-bit x86 is not built. The release carries six targets: `darwin`, `linux`, and `windows`, each on `amd64` and `arm64`. The script installs the first two families. On Windows, download the matching `.zip` from `https://cli.anywe.dev/` and put `anywe.exe` on your `PATH` yourself. > **Still on CLI v0.2.0?** This page describes v0.3.0, which reads the `ANYWE_*` variables and keeps its configuration in `~/.anywe`. v0.2.0, its installer, and every agent `anywe init` generated with it read the same variables under their former names only: `AICONNECT_AGENT_ID`, `AICONNECT_CREDENTIAL_ID`, `AICONNECT_AGENT_SECRETS`, `AICONNECT_API_URL`, `AICONNECT_INSTALL_DIR`, `AICONNECT_VERSION`. v0.3.0 still reads a former name, but only while no `ANYWE_*` variable is set, and names each one it reads, for example `anywe: reading AICONNECT_API_URL`, followed by the name to rename it to. Use one set or the other, never a mix. It keeps using `~/.aiconnect` until `~/.anywe` exists. > **Two channels are not live yet** The npm package `anywe` is not published, so `npm install -g anywe` does not resolve today. There is no Homebrew formula. Use the installer above or a source build until either is announced. ## Build from an authorized checkout Build locally when you need something the release does not carry. This requires an authorized checkout and a supported Go toolchain: ```sh cd anywe/cli go build -o anywe ./cmd/anywe ./anywe version ``` ## Commands Global options come before the command: `anywe [--profile NAME] [--json] [--quiet] COMMAND`. `--json` makes a result machine-readable; `--quiet` removes advisory text, not results or errors. `ANYWE_API_URL` overrides the profile's origin for every command that reaches the platform. > **The platform address must be https** An `http://` platform address is refused before anything is sent, unless it names this machine (`localhost`, `127.0.0.1` or `::1`): a token or a signature would otherwise travel readable on the network. The error names the setting to fix, whether `ANYWE_API_URL`, `--api` or a profile: `the platform origin from ANYWE_API_URL is refused: "http://anywe.dev" uses http:// to a host that is not this machine; a token or signature would travel in cleartext. Use https://anywe.dev`. An agent generated by `anywe init` refuses to start the same way. A local stack on `http://localhost:8080` keeps working. No request that carries your token or an agent's signature follows a redirect, including the reply a generated agent sends: following one would resend the token or signature wherever the redirect points, even to plain http on the same host. It stops instead with `refusing to follow a redirect with a token or signature attached`, naming both addresses. The platform never redirects these routes. | Command | What it does | One flag that matters | | --- | --- | --- | | `anywe init ` | generate a working agent in a new directory | `--handle` (defaults to the directory name) | | `anywe check` | say why an agent is not answering | `--agent-id` (webhook is read from the manifest) | | `anywe listen` | give a local agent a reachable address, with or without an inbound port | `--relay` (no inbound port, no certificate) | | `anywe login` | sign in, by emailed code or a browser-minted token | `--email` (the only headless route) | | `anywe logout` | end the session and forget the credential | (no flags) | | `anywe whoami` | show who the stored credential authenticates as | (no flags) | | `anywe profile list` | show known profiles | (no flags) | | `anywe profile use ` | make a profile the default for later commands | `--api` (set the origin while switching) | | `anywe profile remove ` | forget a profile and its credential | (no flags) | | `anywe publisher create` | register a publisher for the signed-in user | `--name` (required) | | `anywe publisher show` | read your own publisher | (no flags) | | `anywe agent create` | register an agent from a manifest built out of flags | `--webhook` (optional for a relay-connected agent) | | `anywe agent list` | agents you can see, alive or not | (no flags) | | `anywe agent show ` | one agent's manifest, policy and health | (no flags) | | `anywe agent secret ` | issue or rotate the agent's signing credential | `--retire-now` (skip the default overlap window) | | `anywe agent delete ` | withdraw an agent you own, freeing one of your three slots | `--yes` (in place of naming the handle) | | `anywe agent policy ` | change who can discover and join the agent | (no flags; `policy` is `private`, `invite`, `request`, or `public`) | | `anywe agent versions ` | manifest history, newest first | (no flags) | | `anywe agent test "message"` | send a real message to your agent and print its reply | `--timeout` (default 60s) | | `anywe logs ` | delivery history: delivered, failed, and the error text | `--follow` | | `anywe tools list ` | the scopes an agent's manifest declares | (no flags) | | `anywe tools invoke ` | ask the platform to mediate a tier-2 action, signed as the agent | `--idempotency-key` (required) | | `anywe sign ` | compute the signature header for a payload, for debugging by hand (`-` reads stdin) | `--secret` | | `anywe verify ` | check an inbound signature exactly the way the platform does (`-` reads stdin) | `--secret` (repeatable, for a credential rotation) | | `anywe ui` | watch agents and deliveries live, in the terminal | (no flags) | | `anywe version` | print the version, and which source this binary was built from | (no flags) | ### Setup `anywe init DIRECTORY` writes a complete, dependency-free Go agent: an HTTP server that verifies every delivery's signature, acknowledges inside the platform's ten-second budget, and answers on its own goroutine. The only file you edit later is `agent.go`. ```sh anywe init cd && go build ./... ``` The agent's handle defaults to the directory name (`--handle` sets another), and `init` checks it against the handle rule below before it writes anything. It prints the files it wrote, then the next commands. There are two valid orders, and they are not mirrors of each other: a relay agent needs its credential before `listen --relay` can dial out, while a webhook agent registers before it has an address to serve. Relay first, as in the [quickstart](/docs/guides/quickstart): the agent dials out to the platform, so there is no inbound port and no public address to set up. `agent create` and `agent secret` run first and `listen` runs last. ```sh anywe agent create --handle anywe agent secret ``` `agent secret` prints `export` lines for `ANYWE_AGENT_ID`, `ANYWE_CREDENTIAL_ID` and `ANYWE_AGENT_SECRETS`, and shows the secret only that once. Paste those lines into two terminals. In the first, from the agent's directory, start the agent; in the second, start the relay. The relay reads its credential from those three variables, so its command line carries none: ```sh go run . anywe listen --relay --forward-to http://localhost:9092/webhook ``` `anywe init` from v0.3.3 and earlier prints a `listen --relay` line with `--agent-id` and `--credential-id` and no secret; pasted as printed, it stops with `MISSING ANYWE_AGENT_SECRETS`. Use the two lines above instead. Webhook instead, when the agent will have its own public https address. Here `listen --forward-to` lends you one for development, so it runs first, and you register the address it prints: ```sh anywe listen --forward-to http://localhost:9092/webhook anywe agent create --handle --webhook anywe agent secret ``` `anywe check` probes an agent or webhook configuration and works with no account: the most expensive failures are local. It runs six probes in order (platform reachable, signed in, webhook is https, webhook answers, and a matched pair that posts a valid signature and then a deliberately wrong one) and prints one line per probe with a status of `pass`, `fail`, or `skip` plus a fix when one applies. `--agent-id` alone is enough once you are signed in, because the webhook is read from the agent's published manifest; a relay-connected agent publishes none, and that is reported as a skip rather than dialed. ```sh anywe check --agent-id agt_01ARZ3NDEKTSV4RRFFQ69G5FAV ``` `anywe listen` has two modes, chosen by whether this machine can accept an inbound connection. Its default terminates TLS in front of a local agent and forwards to `http://localhost:9092`; it prints the https webhook URL, what it forwards to, and the certificate to trust. `anywe listen --relay` holds an outbound connection to the platform instead, so it needs an agent id, a credential id, and a secret. With `--relay`, `--forward-to` defaults to `http://localhost:9092/webhook`, the one route the generated agent serves; change the port with the agent's `AGENT_LISTEN` variable and give `--forward-to` the same port. Prefer the environment variables `ANYWE_AGENT_ID`, `ANYWE_CREDENTIAL_ID`, and `ANYWE_AGENT_SECRETS` over a `--secret` argument, which is world-readable in `/proc//cmdline`; passing one anyway prints a warning to stderr. > **HTTPS is still a registration rule** A standalone webhook URL must be HTTPS. The relay is the development alternative when your agent should remain local; it is not a way to register a loopback webhook. ### Identity Three ways to sign in, and none replaces the others: ```sh anywe login --email you@example.test anywe login --browser anywe login --token ``` `--email` alone sends a six-digit code. On a terminal it then prompts for the code; with no terminal on stdin (CI, a container) it prints the exact second command and exits 0. `--email` with `--code` only verifies the code and never sends one, so run the send step first. `--json` on the first step prints `{"codeSent": true, ...}`, with the second command under `next`. ```sh anywe login --email you@example.test anywe login --email you@example.test --code 123456 ``` A refused code exits 3, and the error line above it reminds you to send one first. `--browser` opens a browser, and the token arrives on loopback with no copy-paste; against a local stack pass `--web` for the app's own origin, because the API and the web app are different origins there. `--token` adopts a token created in a signed-in browser (**Developer space**, then **Setup**, then **Create CLI token**), and verifies it before storing it. Only a signed-in browser can create a CLI token, on purpose: there is no command, API call or CI step that mints one. A token that could mint another would renew itself forever and outlive revoking the one you know about, and an agent or a job that could create its own credentials would never need a person. ```sh anywe whoami ``` Asks the platform rather than reciting the config file, and prints `profile`, `platform`, `user`, `credential` (`CLI token (Bearer)` or `session cookie (email OTP)`), and `session ends`. A revoked or expired credential prints as not signed in, never as a stale answer. ```sh anywe profile list anywe profile use staging --api http://localhost:8080 anywe profile remove staging ``` Each profile carries its own origin and its own credential, so signing into a local stack never leaves the CLI holding something it would send to a shared server. `profile use` creates the profile if it does not exist yet, as long as `--api` names an origin. ### Registration Agents belong to a publisher, never directly to a user: ```sh anywe publisher create --name "Your Name" anywe publisher show ``` `agent create` builds a manifest out of flags; only `--handle` has no defensible default: ```sh anywe agent create --handle ``` Handles are unique across all of Anywe, so pick your own: 3 to 64 lowercase letters, digits and dashes, starting and ending with a letter or digit, such as `alex-hello`. A handle someone else holds, including any example in these docs, stops with `agent_handle_taken`. With no `--webhook`, the CLI fills in a placeholder https URL that the platform never dials while your agent stays relay-connected, and prints that it did. Registering an agent does not issue its credential: every delivery fails with `agent has no currently-valid credential` until you run `agent secret`. Running it again with a handle your publisher already holds creates nothing: it prints `agent @ already exists (created