#Using it from a terminal (the samuraiapp command)

samuraiapp help prints the command list, so this file covers only the shape and the key points.

This knowledge can be downloaded from the screen as a skill. On 「PC と繋ぐ」 (/settings/cli), get samuraiapp-cli.zip from 「手元のエージェントへ使い方を渡す」 and extract it under ~/.claude/skills/. The downloaded copy has the connection target (host and tenant ID) baked in — fixes here do not reach your local copy, so download it again if the content seems stale.

#Install

curl -fsSL https://<ホスト>/install.sh | sh

On Windows, in PowerShell:

irm https://<ホスト>/install.ps1 | iex

It installs to $HOME/.local/bin (on Windows, %LOCALAPPDATA%\Programs\samuraiapp). No administrator rights needed.

The installer sets up PATH. On macOS / Linux it adds 2 lines starting with # samuraiapp to the config of the shell matching $SHELL (~/.zshrc for zsh; for bash, ~/.bash_profile on mac / ~/.bashrc on Linux) — it creates the file if missing, and reinstalling does not add them again. To apply it in the terminal already open, run source ~/.zshrc (or open a new tab). On Windows it adds to the user-scope PATH and also applies to the PowerShell already open, so you can run it right after installing.

To keep your config untouched, set SAMURAIAPP_NO_MODIFY_PATH=1 (it writes nothing and only prints the 1 line to add). Shells it cannot identify, such as fish, also get the printed line only.

Updates are automatic (only for the installed binary). When a new version is out, it is swapped in the next time you run a command, and that command runs on the new version as is. To stop this, set the environment variable SAMURAIAPP_NO_AUTO_UPDATE=1 (meanwhile only a 1-line "new version available" notice appears). To update by hand, run samuraiapp upgrade. The version is samuraiapp version.

#Operating from a screen (no flags to memorize)

samuraiapp

Running it with no arguments opens an interactive screen. It walks you through signing in, registering and connecting this machine (tunnel), and recording your work (record) — no flags needed at all. You choose with the arrow keys and Enter; the only things you type are the MCP URL, the path of the folder to allow, and this machine's name (the folder path cannot be skipped with an empty Enter). Every step has 「戻る」 to go back one step; on a step where you type, press Esc instead (on the first sign-in step, Esc closes the screen). The keys each screen accepts are shown on its last line. Close it with 「終了」 in the menu. Choosing 「サインアウト」 also clears the saved sign-in and closes the screen (it does not return to the sign-in screen; to keep using it, run samuraiapp again). When run from something other than a terminal (a script, CI, an agent's shell), the screen does not open and it prints the same list as samuraiapp help, as before.

On the last step of registering, 「コマンドを表示して終了する」 closes the screen and prints the same registration as one samuraiapp tunnel register … line, without registering. Copy it from there — on a narrow terminal the copy shown on the screen is broken across lines.

You can also open it pointed at a target: samuraiapp --env stg / samuraiapp --origin http://localhost:5173.

All the one-shot commands below still work as before. The screen exists so you do not have to memorize them; it does not replace them.

#Sign in

samuraiapp login https://<ホスト>/mcp/<テナント ID>

The URL you pass is the same one you paste into Claude or ChatGPT. You do not need to remember two kinds of connection targets, and the URL itself says which tenant it points to (the token has no tenant baked in).

A browser opens; sign in there. Once you are back, you are done.

The account that gets authorized is the one signed in to the browser that opened the URL. If a different account is signed in to your default browser, authorization completes with that one — on a mismatch the CLI refuses without saving, so reopen the URL in a browser signed in to that tenant's account.

You can sign in to multiple tenants on the same host. With 2 or more, name one:

samuraiapp --tenant <テナント ID> <resource> <action>

samuraiapp logout [--all]  Remove the sign-in (only for the tenant in use; --all removes all)

#Run a conversation

samuraiapp chat                          New conversation
samuraiapp chat --conversation <conversation ID>   Continue an existing one

#Resource commands

There is only one shape:

samuraiapp <resource> <action> [--key value]

Action names work with either hyphens or underscores (set-role = set_role).

Action names and --key are not listed here. The only way to learn the real ones is samuraiapp --help. Example lines built from plausible names (create / list, etc.) will always drift from the real thing — the one SIROE line below is kept in step with the CLI.

To pass several values, repeat the same flag (--label-id a --label-id b).

Delete operations ask for confirmation before running. Nothing proceeds until you answer y. When running from a pipe or CI, add --yes — without it, it refuses and does not run (so nothing is silently deleted where it cannot ask).

There are 21 resources:

On SIROE, add-element places a sticky where nothing overlaps:

samuraiapp siroe add-element --id <page id> --kind sticky --text "案"

A meeting with a calendar event (deleting an event and ending a meeting ask first; --yes skips):

samuraiapp meeting create --title "定例" --scheduled-at 2026-10-23T10:00
samuraiapp calendar create-event --title "定例" --starts-at 2026-10-23T10:00 --ends-at 2026-10-23T11:00 --attendees <user id> --groups 営業部 --guests partner@client.example
samuraiapp calendar link-meeting --id <event id> --meeting-id <mtg_…>
samuraiapp meeting transcript --id <mtg_…>

For the list and arguments:

samuraiapp help              List of resources
samuraiapp <resource> --help     That resource's actions and arguments

#Editing a workflow from your terminal

A local agent (Claude Code etc.) can build a workflow end to end. Read how to write the doc first, then write, test, and publish:

samuraiapp workflow guide                         How to write the doc
samuraiapp workflow write --id <id> --base-version-id <versionId> --doc "$(cat doc.json)"
samuraiapp workflow test-step --id <id> --step-id <step id>
samuraiapp workflow publish --id <id> --version-id <versionId>

Publishing, and running or testing a version that is not published, do not happen right away. They return 202 with a request and the workflow's URL. A person who can edit (publish) or run (run) the workflow sees the request at the top of its screen and presses 承認 or 却下; it then runs in that person's name. Check the outcome with samuraiapp workflow get-request --id --request-id (an approved run carries runId). A newer request of the same kind replaces the older one. Running the published version starts at once. Answering a workflow's 人の確認 wait is done on screen.

#Calling endpoints not in the manifest

samuraiapp request list-endpoints   List of callable endpoints
samuraiapp request GET /api/me
samuraiapp request POST /api/conversations '{"title":"見積の確認"}'

list-endpoints shows what you can call. Endpoints that are not tools are listed with the reason.

Authorization goes through exactly the same path as the other commands. Only the surface widens; permissions do not.

Restrictions:

• It cannot go outside /api/ (a path like /api/../mcp/... is normalized before it is checked)
• Access-source restrictions, single sign-on settings, registering SaaS API credentials, and removing members are blocked here. These are human decisions, so do them from the screen

#Resident mode (letting the agent use your local machine)

samuraiapp tunnel register --path <directory>   Register (does not connect)
samuraiapp tunnel install                          Connect automatically
samuraiapp tunnel serve                            Connect just this once

--path is required (unless --pick-folder is passed). Nothing outside the allowed directories is reachable. You can pass several. --pick-folder opens the OS folder dialog on the machine running the command — Finder on macOS (several at once), a folder window on Windows (one), zenity on Linux — and adds the chosen absolute paths to any --path. Closing it without choosing registers nothing, and it refuses to run where nobody is watching (auto-start, scripts). The first --path is the starting point for relative paths. In a conversation or a saved skill, a file can be named relative to it (demodata/sales.xlsx), and scripts run in that folder too — so a skill shared with a teammate works on their machine when both register the same layout. ~ is not expanded.

Each kind of permission is granted separately. Anything not granted cannot be done.

Preparing --desktop (operating local apps). Do this on the device before registering — without cua-driver, connecting refuses --desktop altogether. Turning on 「PC のアプリ」 in 「PC と繋ぐ」 → 「使う」 shows the same steps.

1. Install cua-driver with the upstream installer
   • macOS: /bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"
   • Windows (PowerShell): irm https://cua.ai/driver/install.ps1 | iex (upstream's cua-driver autostart is not needed — the resident process starts cua-driver itself, unelevated)
2. macOS only: run cua-driver permissions grant and, following the prompts, turn CuaDriver on under System Settings 「アクセシビリティ」 and 「画面収録」

What the agent can do: list running apps and windows, view one window's screen and its elements (read), and operate that window by clicking and typing when told what to accomplish (write). Viewing and operating both ask for approval once per app per conversation. On Windows, windows running as administrator and the UAC screen cannot be operated. Linux is not supported.

--agent claude-code needs a Claude Pro / Max subscription with the official claude CLI installed and signed in on this device (the resident starts it as an unmodified child process; it never reads or relays your Claude credentials). Install it with curl -fsSL https://claude.ai/install.sh | bash (macOS / Linux) or irm https://claude.ai/install.ps1 | iex (Windows PowerShell), then run claude once and sign in with the Pro / Max account. The 「使う」 tab of 「PC と繋ぐ」 (/settings/cli) has a 「手元の Claude Code」 step — turning on 「会話を手元の Claude Code に任せる」 adds --agent claude-code to the command and shows these two steps right there. Once registered and connected (tunnel serve or install), the new-conversation screen's 「実行する AI」 offers 「手元の Claude Code」 — only there, for your own private conversation (never for team or channel conversations). In that conversation, only the Samurai App MCP tools reach it — browsing, code execution, running skills, and web search are not available, permission prompts route to the usual approval card, and the reply appears only once the whole turn ends (no intermediate steps stream in this first version), within a 30-minute window per turn. If nothing comes back, the conversation shows a notice with a 「再送」 button that resends the same text. If claude is not installed on the device, the turn is refused right away with a message to install Claude Code and sign in. The conversation continues the device's own Claude Code session only on the device that holds it; on another device, or when that session is gone, it starts a fresh session with the conversation so far.

Dedicated profiles keep their sign-in state. Naming profiles apart with --profile lets one device hold separate sign-ins for testing and production (deletion is manual — the product has no reset endpoint).

Sign-ins stored in 「ブラウザ認証」 also go into the device's browser. They are applied when the agent opens that site in the device's browser, and 1 line on the device's screen shows the sites and count applied (no values are shown). For registered IDs and passwords, it signs in automatically on the login page. Switching accounts removes that site's cookies and sign-in from the device's browser. If connected with --attach, they are removed from your everyday Chrome (sign-ins for other sites stay). Applied sign-ins stay in the device's browser. They are not removed when the conversation ends. To stop the agent from using them, revoke the device (tunnel revoke). To remove the sign-in left in the browser itself, sign out in that browser.

Browser operations need Google Chrome or Microsoft Edge on that device. This holds with or without --attach; even the default, which launches a dedicated profile, uses the user's browser. On a device with neither installed, only browser operations fail (file operations and script execution work). --channel edge selects Edge — what is observed has the same shape as Chrome.

install returns as soon as it is set up. No administrator rights needed; it connects automatically from the next login. serve reaches your machine only while connected. It does not return, so work in a separate terminal (it reconnects if the line drops). In the interactive screen, while it is waiting to reconnect, 「今すぐ繋ぎ直す」 retries without waiting.

When this device has multiple saved registrations, add --device to install / serve (it can be omitted if there is only 1).

samuraiapp tunnel status            Registered devices and resident status
samuraiapp tunnel uninstall         Stop automatic startup
samuraiapp tunnel revoke <device ID>   Revoke a device
samuraiapp tunnel kill-browser      Force-quit the browser holding this device's dedicated profile

A running serve holds the dedicated profile. While a serve is still running — in another terminal, or as automatic startup — no other browser can open that profile, and opening it by hand fails (That browser profile is already in use). With --headless there is no window to close — run samuraiapp tunnel kill-browser (add --device when several are registered). It stops only the browser launched on that device's dedicated profile (a record start window on it closes too), and refuses for --attach devices, because that is your everyday Chrome. A serve that is still running opens it again on its next browser operation — to keep it closed, stop that serve (Ctrl-C in its terminal, or tunnel uninstall).

Devices revoked from the screen are marked (revoked) by tunnel status. The tunnel revoke shown next to it also removes the local registration — it works even if the server no longer has it. A revoked or expired registration cannot connect again — register this machine again. In the interactive screen, 「今すぐ繋ぐ」 and 「ログイン時に自動で繋ぐ」 offer only registrations that still work (both are hidden when none does, with 「使用できる登録がありません。「この PC を登録する」から登録し直してください」), and 「使用できない登録を削除する」 removes every revoked or expired registration from this machine at once.

samuraiapp tunnel or samuraiapp help tunnel prints the list and arguments.

#Using the device from a scheduled run

A scheduled run (「定期実行」) can operate the device's browser, under these conditions:

• Register with --browser and connect with install. register alone does not connect, and serve only reaches the device while that terminal stays open. --headless keeps the window from appearing and stealing focus
• Keep exactly 1 device connected. With 2 or more online, the run is refused and the devices are named
• It only reaches the devices of the person who created the schedule. Someone else's schedule never reaches your device
• Nobody is there to answer. An operation that would raise an approval card is refused on the spot instead, and the agent cannot ask a question midway — a procedure that stops to confirm something with a person does not finish in a scheduled run. Browser operations on the device ask for approval every time by default, so as is, the run stops at the first browser operation

There are 2 ways to let it through:

1. Save the procedure as a skill with a script, and approve the script once in a conversation. The approved version keeps running under the schedule. Editing the script makes a new version, which needs approval again
2. Declare the operations on the schedule (「この自動実行が使う操作」 on the trigger's page, or operationKeys on the trigger resource). A key names the operation and the host, such as local.browser.read@ for viewing and local.browser.write@ for typing and clicking. Keys must match exactly, host included — no wildcards, up to 20 keys. A skill script's own approval cannot be declared this way; use 1

You do not have to work the keys out yourself. The operations a run was refused are listed on the trigger's page and can be allowed right there; from the terminal, the trigger resource reads them (samuraiapp trigger --help).

If the tenant has blocked 「手元の機械で動かす(全体)」 in 「許可設定」, neither way gets through.

#Recording your own work to turn it into a procedure

You can record yourself operating business screens as usual, and use that as material for a detailed procedure document, or for a skill when you ask for one (「録画をスキルにして」). Only the browser is recorded, and the recording stays on the device — nothing is uploaded to Samurai App until you run build. To record without installing anything on the device, you can also use 「録画」 in the conversation's browser panel (the screen guides you).

First run tunnel register from the "Resident mode" section with --browser read.

Recording does not need the device connected. record start and build do not go through tunnel serve / install — only letting the agent run the resulting procedure on this device's browser does. record start opens the registered browser with a window, even for a --headless registration, and uses the agent's dedicated profile, so a site you sign in to while recording stays signed in for the agent.

samuraiapp record start          Start recording (ends with Ctrl-C)
samuraiapp record list           List recordings
samuraiapp record show <recording ID>  Read the step sequence
samuraiapp record build <recording ID> Check the content, then turn it into a conversation that builds the procedure
samuraiapp record delete <recording ID>  Delete one (--all deletes all)

Finish with Ctrl-C. record start stays in the foreground recording, and on Ctrl-C it assembles the step sequence and writes it out. There is no other way to stop it. When recording ends, the show and build commands are printed.

record start always opens a window, even when the device was registered with --headless — you operate it yourself. It works while serve or automatic startup is connected: the resident browser closes and lends the dedicated profile to the recording (sign-ins carry over), and the agent's browser operations on this device wait until you stop recording. If the profile does not come free within about 15 seconds, it stops with the tunnel kill-browser guidance above.

--attach is not recommended. From Chrome 136 on, CDP does not open on the default profile — it is about the storage location, so specifying the path explicitly does not get around it. It needs a separate location, which is also empty and needs 1 sign-in. A dedicated profile (no --attach) needs no launch effort.

Before sending, build lists the input values to be sent as is and the values that appeared on screen. Masking only applies to fixed-format items (card numbers, keys, password fields), so check here that no internal proper names or numbers are mixed in. It refuses when no human is watching (--yes skips this).

Recordings stay on the device even after upload. They contain input values that masking did not catch and values that appeared on screen, so delete them when no longer needed (it shows what will be deleted and asks; --yes skips this).

There is no dedicated place for recordings. The step sequence is uploaded as 1 item in the file ledger and passed as a conversation attachment — deleting the conversation deletes the attachment with it, and the content can be opened and read from the attachment in the message bubble. build starts a conversation, runs it through the first turn, and prints that conversation's URL. The intent and steps it read are shown, and it does not proceed to saving until you confirm.

#Stopping use

The order matters. The same 4 steps are also collapsed on the 「PC と繋ぐ」 screen.

1. samuraiapp tunnel uninstall — stop automatic startup
2. samuraiapp tunnel revoke — revoke the device (tunnel status shows the device ID. 「失効させる」 under 「登録した端末」 on the screen does the same)
3. samuraiapp logout --all — remove credentials
4. Delete the binary and config

logout does not stop resident mode. Only credentials.json is removed and the device credentials remain, so do 1 and 2 first. revoke calls the server, so it only works before you sign out.

Where the binary and config live:

There is no uninstall subcommand. Windows cannot delete a running binary, so delete it by hand. The PATH written at install time remains after the binary is deleted — on macOS / Linux, the 2 lines starting with # samuraiapp in the shell config; on Windows, the entry in the user-scope PATH (「設定 → システム → システムの詳細設定 → 環境変数」; harmless once the folder is deleted).

#Frequently asked

• Pass the MCP URL appears — samuraiapp login needs a URL. The shape is https://<ホスト>/mcp/<テナント ID> (the text the CLI writes to the terminal is English)
• Signed in as a different account appears — the browser that opened the authorization URL is signed in to a different account. Reopen it in a browser signed in to that tenant's account, or sign the other account out first. The sign-in was not saved, so just try again
• 2 tenants are signed in at … appears — you are signed in to multiple tenants on the same host. Name one with --tenant <テナント ID> (the refusal lists the tenant IDs)
• Not sure which actions each resource has — samuraiapp --help. They are not copied into this knowledge (a copy always drifts from the real thing)
• Stopped waiting for approval — read with samuraiapp approval list and answer with samuraiapp approval respond
• tunnel serve does not connect / drops right away — access-source restrictions apply to resident mode too. The current network is not allowed
• Does not connect after a restart — run samuraiapp tunnel install once
• Does not connect behind a company proxy — set HTTPS_PROXY (and NO_PROXY). The OS's static proxy setting is read too (also by resident mode). On Windows a PAC / WPAD setting is evaluated through the OS; on a Mac it is not. The Chrome the CLI opens is given the PAC / WPAD setting explicitly. Company CAs installed in the OS are trusted
• This machine picks its proxy through a proxy auto-config script (…) appears — the company network chooses the proxy through a PAC file the CLI could not evaluate (on a Mac it never does; on Windows the OS evaluation failed). Get the proxy's host:port from IT (or open the URL in the parentheses in a browser and read the PROXY host:port it returns). On Windows run setx HTTPS_PROXY http://: once, close the terminal, and run the command again in a new one. Resident mode started from Startup reads it from the next sign-in. If the parentheses show a registry path (HKEY_CURRENT_USER\…) instead of a URL, the CLI is older than the fix for a misread — run samuraiapp upgrade