Quick start

Install

macOS and Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/brnyxx/itda-cli/releases/latest/download/itda-cli-installer.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -c "irm https://github.com/brnyxx/itda-cli/releases/latest/download/itda-cli-installer.ps1 | iex"

Download an archive from Releases, or build from source with cargo install --git https://github.com/brnyxx/itda-cli itda-cli.

Claude Desktop, with no terminal: download the bundle for macOS (Apple silicon), macOS (Intel) or Windows and open the file. Claude Desktop installs itda with its tools, and “use the-site-you-use.example” sets a site up from inside the conversation. Approving a change still happens in a terminal with itda approve, so for changes install the command too.

Check the setup:

$ itda doctor
itda 0.7.0
ok    data directory   /home/you/.local/share/itda
ok    secrets          system keyring; long secrets sealed in ~/.local/share/itda/vault.sealed with a key from the keyring
ok    audit log        0 records, chain intact
ok    changes          none with an unknown outcome
ok    sites            0 installed, 0 invalid
ok    agents           none connected (itda setup <url>, or itda mcp install <client>)
ok    local addresses  refused (ITDA_ALLOW_LOCAL=1 allows them)

Set up a site you use

Type itda and paste the address of a site you use. Press Enter. itda looks at the page. When the page is drawn by scripts and shows itda only a title, it opens your browser on it for a few seconds. It watches what the page loads by itself and drafts from those calls. Nothing is clicked or typed, and the window closes on its own. If the page needs a sign-in, it asks for your user name and password and fills in the site’s own form for you (--user <name> from a script, the password on stdin). Or it asks to open your browser and watch you use the site. It shows what agents can do and tries every read. After one more Enter, it connects the agent apps it finds on your computer. From then on, ask your agent for things on that site. itda setup <address> does the same from a script. --no-record never opens the browser; --watch-only watches but never asks you to record. itda setup --help lists the flags. itda speaks the language of your LANG; ITDA_LANG=ja (or any tag in docs/i18n.md) overrides it.

itda recognises sites running known software (GitLab, Jira, Confluence, Redmine, Discourse, MediaWiki, WordPress, Gitea or Forgejo) from their pages and confirms each with one request to the software’s own API. itda then says “This looks like GitLab. Using its API at .” and the agent gets the software’s real reads and changes from a ready-made template, with the page’s own lists and forms joining them. --as <software> forces a template when the page does not say; --no-template skips them.

From inside your agent

Once itda is connected (itda mcp install <client>, or the question at the end of a setup), you can skip the terminal for the next sites. Tell your agent “use news.ycombinator.com”. It calls itda_setup with the address. itda looks at the site, drafts and tries it the same way. Its actions appear as tools in the same conversation. A page drawn by scripts opens briefly in a browser window on your screen. itda watches what it loads without clicking or typing. When a read says to sign in, the agent calls itda_login. Your own browser opens for you to sign in; the agent only sees the account id. itda_check, itda_sites and itda_manage cover checking, listing, removing and resuming sites and reading approvals and the audit log, with a form for you to confirm the ones that change something. Nothing an agent can call approves a change.

Try the sandbox

The repository includes a small fake intranet that only listens on 127.0.0.1: a notice board with an HTML table, a JSON API behind an API key, and a page that refuses automated access.

git clone https://github.com/brnyxx/itda-cli && cd itda-cli
cargo run -p itda-sandbox            # http://127.0.0.1:8787

In another terminal, use a scratch data directory and install its definition:

export ITDA_HOME=$(mktemp -d) ITDA_ALLOW_LOCAL=1
mkdir -p "$ITDA_HOME/specs/sandbox"
cp examples/sandbox/spec.yaml "$ITDA_HOME/specs/sandbox/"
itda ls

Read, sign in, and see what happens when a site says no:

itda call sandbox.list-notices --q 보안      # JSON API
itda call sandbox.notice-board --json       # HTML table extracted into records
itda call sandbox.me                        # exit 10: no API key yet
echo sandbox-key | itda login sandbox       # stores the key in the OS keyring
itda call sandbox.me                        # signed in
itda call sandbox.reports                   # exit 12: refused, in your browser too; nothing is paused

Make a change:

itda call sandbox.create-notice --title hi  # exit 20: waits for approval <id>
itda approve <id>                           # shows what it does and the exact request, asks y/N
itda call sandbox.create-notice --title hi --approval <id>
itda audit                                  # everything above, hash-chained
itda describe sandbox                       # every action with its inputs and a command to copy

Without a keyring (CI, containers), skip itda login and set ITDA_SECRET_STORE=env ITDA_SECRET__SANDBOX__DEFAULT__API_KEY=sandbox-key.

Requests to one site go one at a time, about 1.2 seconds apart, as on a real website. Consecutive or parallel calls take a moment. A site definition can ask for more room with defaults.interval.

Commands