# Skill > Odevio — from a Flutter project to an iPhone - Skill: `odevio/skill` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add odevio/skill` - Raw SKILL.md: https://api.skillmd.com/api/skills/odevio/skill/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Odevio (https://skillmd.com/u/odevio) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/odevio/skill --- # Odevio — from a Flutter project to an iPhone Odevio builds and signs iOS apps on remote Macs. The user needs no Mac and no iOS knowledge: certificates, provisioning profiles and app identifiers are already automated. This skill drives the whole path and asks as little as possible. Read this file fully before acting. Then read a reference only when its situation arises: | Reference | Read it when | | ---------------------------------- | -------------------------------------------------------------------------------------- | | `references/first-time-setup.md` | no Apple developer account registered, or no Odevio app for this project | | `references/when-a-build-fails.md` | a build failed | | `references/delivery.md` | a build succeeded | | `references/app-store-listing.md` | the goal is the App Store — read it **before building**, not after | | `references/cli-contract.md` | you are unsure how a command behaves — it records what was learned by getting it wrong | | `references/voice.md` | **always, before acting** - how to speak; the words never to use | --- # Before anything — make sure Odevio is installed This skill drives the `odevio` command; it does nothing without it. If you reached this skill through discovery rather than `odevio skill install`, the CLI may not be present yet. Check once, install if missing: ```bash odevio --version || pip install odevio ``` Use `pipx install odevio` instead if this machine's Python is externally managed. Then, so the commands below run without a permission prompt each time, register the skill for your agent once: ```bash odevio skill install ``` Neither step re-does anything already done — both are safe to run when Odevio is already set up. --- # How to talk to the user **This matters as much as the mechanics.** The words never to use, when to stay silent, and how to ask a question live in `references/voice.md`. Read it before you act - it is not optional. --- # Step 0 — What do they actually want Their goal decides the kind of build, whether Apple's side needs setting up at all, and what "done" means. It is the one thing you cannot read from the project. **If the way they asked already says it** — "get my app on my phone", "publish it", "does this even build" — take it and never ask again. **If they gave no clue**, for instance a bare invocation, ask once, in outcomes, never with type names. Offer these five, and **all five**, whatever form the question takes: | Offer it as | Never as | | ----------------------------------------------- | --------------------------------------- | | See it running on a Mac we provide | a configuration build, a remote desktop | | Try it on your own iPhone | ad-hoc | | Share it with a few testers, through TestFlight | publication | | **Put it on the App Store** | publication | | Just check that it compiles | distribution | **Publishing to the App Store is its own answer, and the one most easily lost.** It shares a build with the testers option, which makes it tempting to fold the two together — do not. They lead to entirely different work: testers means the app is with Apple and you are finished, while the App Store means a page has to be written, pictures provided and a questionnaire answered. Someone who meant to publish and was offered only "send to testers" has no way of knowing the rest exists. The wording of each option is what the user reads, so **no build type ever appears in it** — not in the heading, not in the explanatory line underneath. "Sends it to Apple and puts it in front of your testers" says what happens. "Build publication — envoi chez Apple" leaks the machinery and tells them nothing they can act on. The first option matters more than it looks: **seeing it running needs no Apple account at all.** Everything else on that list requires a paid Apple developer account, so for someone who has not paid yet, that is the only thing you can offer today — and it is a real one, not a consolation prize. Do not skip this and default to compiling. A silent assumption is worse than a question here: it spends a quarter of an hour producing something they did not ask for, and the App Store route needs a manual step that the others do not. **If they said the App Store, read the page before doing anything else.** Not after building — before. Go to `references/app-store-listing.md` now and run `odevio app store-status`. The reason is concrete: **Apple may already hold a build.** Building takes a quarter of an hour and occupies a machine someone else is waiting for, and there is no point spending either if what is needed is a description and three pictures. Only the page can say which of the two it is. Then say what the whole thing involves, and what you are about to do first. Sending the app is the easy half; the page has to be filled in too, and two parts of it can only be done on Apple's own website: > Right — the App Store. Two things there that only you can do, about ten minutes in total: creating the > app's page, and answering Apple's questions about data. I will tell you exactly what to click. > > Let me look at where your page stands before anything else — if your app is already with Apple there is no > need to build it again. Only once the page has been read does building become a question, and then it is one to put to them rather than assume. `references/app-store-listing.md` covers the three cases. --- # Step 1 — Find out what is already there Read the state before asking anything. Stop at the first blocking check. **Run as few commands as will do.** Every one appears in front of the user as a block of shell and output, and a screenful of it before the first sentence makes a tool that promised to handle things look like it is rummaging. Two rules keep it short: - **Never inspect your own installation.** Listing the skill's own directory, reading its own files to see what is there, checking where it is installed — none of that tells you anything about their project and all of it is visible to them. - **One command per fact, and only facts you are about to use.** `odevio profile` proves the CLI is installed _and_ that there is a session, so `odevio --version` on top of it earns nothing. Their version is worth having only when something has already gone wrong. | # | Check | If missing | | --- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 1 | `odevio profile` — is the CLI there, and is there a session? | **blocking** — if the command is not found, offer `pip install odevio` and stop; do not install it yourself, as the wrong Python environment is worse than none. If it asks for credentials, see below | | 2 | `odevio app ls` — an app matching this project? | `references/first-time-setup.md` | | 3 | `odevio apple ls` — any Apple account registered? Only needed when step 2 found nothing, since an app already carries its account | `references/first-time-setup.md` | | 4 | `pubspec.yaml` and `lib/` present? | **blocking** — say they are not in a Flutter project and stop, rather than uploading an unrelated directory | From `pubspec.yaml`, record without asking: the app name, the version, and the build number after `+`. Note any `.odevio` file, and the identifier already configured in the project. Match step 2 against that identifier. A match settles both the app and the Apple account, so neither is asked. Only if several plausible matches remain do you ask — showing names, never internal keys. **If step 1 asks for credentials**, this is one of the hand-overs. You cannot sign in for them: these commands prompt, and a prompt without a terminal dies on an error rather than working. > You need to sign in to Odevio first — run `odevio signin` in your terminal, it'll ask for your e-mail and > password. Tell me when it's done and I'll carry on from there. With no Odevio account at all, offer both `odevio signup` and creating it on https://odevio.com, usually gentler the first time. When they say they are done, verify with `odevio profile` rather than taking their word. **What the user sees from this step: almost nothing.** These checks are your bookkeeping. When everything is in place, that is one warm sentence and you carry on. --- # Step 2 — Check locally, for free Before spending a remote build, run what costs nothing: 1. `flutter pub get` — failures here are a typo in `pubspec.yaml`, or a package that does not exist 2. `dart analyze` — catches most beginner mistakes 3. `flutter test` — skip silently when there is no test directory; a fresh project with no tests is normal Fix what they report locally, in a loop, without touching Odevio. **Do not run `flutter build apk`.** It needs the whole Android toolchain, which the user may not have, and an Android failure says nothing about an iOS build — a pass gives false confidence, a failure sends you chasing an irrelevant problem. **Do not attempt an iOS build locally.** Not having a Mac is the whole reason Odevio exists. Be honest about what this proves: nothing about iOS. Native plugins, CocoaPods, Xcode configuration and the deployment target can only surface on the remote build. A project can pass all three checks and still fail on iOS — that is the normal case this skill exists to handle. --- # Step 3 — Build ## Map the goal onto a build type The goal came from Step 0. Translate it here, and never discuss type names with the user — they do not know them and explaining them is not a service. **Everything in this table is for you.** None of its wording belongs in a message or in a list of choices, and the right-hand column least of all. Copying a row into an option is how `publication` and `ad-hoc` end up in front of someone who came here to avoid exactly that. | What they said they want | Type | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | see it running, without paying Apple anything | `configuration` — a Mac desktop with their project and the iOS simulator. **No Apple account, no certificate, no app needed** | | try it on their own phone, nothing shared | `ad-hoc` — installs straight from a link or QR code, needs the device registered first | | share it with a few testers | `publication` — uploads to Apple, feeds TestFlight | | put it on the App Store | **do not come here first** — `references/app-store-listing.md` decides whether a build is needed at all, since Apple may already hold one. When one is needed it is `publication`, the same as the testers option, with entirely different work afterwards | | just check that it builds | `distribution` — builds and signs, uploads nothing | A `configuration` build is the only type that survives without Apple credentials: the server tolerates the failure to send them for this type alone. See `references/delivery.md` for what to tell them about it. If you reach this point still not knowing, go back to Step 0 and ask. Do not pick one on their behalf. ## Build the type they actually want, from the first attempt **Do not run a verification build first.** It costs a full fifteen minutes and a slot on a shared Mac to produce something that cannot be installed, and then the real build has to run anyway. For a project that compiles — the common case — the whole job should be **one** build. What the server actually meters, checked in its code, makes this safe: - there is **no per-build credit**. The only limit is a rate: a free account may publish once every few days - it applies **only to free accounts**, and only for apps outside a team. Paid accounts and team apps have no limit at all - only `validation` and `publication` count towards it. `distribution` and `ad-hoc` count for nothing - a **failed** build does not count either: `FAIL` and `STOP` are excluded from the statuses considered So retrying a failed `publication` is free of quota consequences, and there is no reason to detour through a throwaway build. Use `distribution` in exactly one case: when the goal from Step 0 was only to check that the app builds. One thing to watch, for a free account only: a publication that is queued or running does count while it is in flight. So never launch a second one alongside it — which the rule against two concurrent builds already covers. ## Launch ```sh COLUMNS=200 odevio build start \ --build-type --no-progress --flutter --build-number ``` - **put `COLUMNS=200` in front of the command itself**, as above — never `export COLUMNS=200;` followed by the command. The default 80-column formatting wraps long values onto continuation lines and silently breaks parsing, but a chained command also loses the permissions this skill was granted, so the user is asked to approve something that should have been silent. See the rule on running one command at a time - **increment `--build-number` on every attempt**, or a reused number triggers an interactive confirmation - prefer a Flutter version already on the host: the first build of a new one pays to download and extract a 2.2 GB SDK, and that space is never reclaimed Take the key from the output, between the quotes: ``` Build #8 has been registered. It has key "K7B3Q" and will be started as soon as possible. ``` No key means stop. Never continue without knowing which build to follow. ## Follow **Watch it without blocking yourself.** Start the watcher in the background, so you stay able to answer while it runs, and let it tell you when something changes. Never sit in a foreground loop of `sleep` calls: it locks you up for minutes at a time, and you have just promised the user they can ask you anything — a promise you cannot keep while blocked. If the host offers no way to watch in the background, say honestly that you will check back rather than claiming to be reachable. **Warn them that starting the watcher asks for approval.** Whatever runs a background task is not among the commands this skill was granted in advance, and deliberately so: it can carry any shell command inside it, so pre-approving it would quietly undo the care taken to have anything touching Apple confirmed. The user therefore sees a prompt full of shell they have no way to judge, at the exact moment you told them to relax. **Put the loop in the command itself, never in a script file you then run.** Approving `zsh /tmp/…/watch.sh` asks someone to trust a path they cannot read; approving the loop shows them a poll of `odevio build detail` and a `sleep`, which is at least judgeable. Same prompt either way — one of them treats them as an adult. Say what it is before it appears, in the same message as the waiting one: > Your app is building. Your tool will ask you to approve one thing — it is just how I keep an eye on the > build without blocking this conversation. Allow it and there is nothing else to do. What to watch: `COLUMNS=200 odevio build detail `, roughly every 20 seconds, reading the `Status :` line. Stop on **any** end state — `Succeeded`, `Failed`, `Stopped`, or `Configuration for remote desktop` — not only on the first two: ``` Waiting for available instance → In progress - Starting instance → In progress - Preparing build → In progress - Building app → Failed or Succeeded ``` **A `configuration` build never reaches `Succeeded`.** Its finish line is a different status, `Configuration for remote desktop`, because the Mac is now waiting for the user rather than having produced something. Watch for that one, and treat it exactly as success — the moment it appears, fetch the connection details and hand them over **without being asked**. Waiting for `Succeeded` on this type means waiting for ever while the user sits in front of a ready machine. Whatever you promised in your waiting message, deliver it the moment the build reaches its end state. If you said "I'll give you the connection details as soon as it's ready", that is a commitment to act on the transition, not something to produce when prodded. Translate for the user, never quote: waiting for a free Mac; the Mac is starting up; getting your project ready; compiling, which is the long part; and for a `configuration` build, your Mac is ready. Three things to handle: - **a poll can return nothing.** Roughly one in thirty gives no status line. Treat it as "unknown, poll again", never as an ending - **queueing is normal** — 8 minutes 30 seconds was measured behind one other build. Say so, or silence reads as a freeze - **queueing can also be permanent.** Stale records on the server make a host look busy for ever, with no error anywhere. Past ten minutes queued, stop and tell them to have someone check the server side **If they ask where it's at**, answer from a fresh `build detail`, in plain words, then say again there is nothing to do and go back to watching. **Being interrupted must never start a second build** — resume following the one already running. If they ask you to stop: `odevio build stop `. ## What it really costs Measured on an empty project, so a floor rather than an average: | Queueing | VM start and preparation | Xcode archive | Whole build | | ---------- | ------------------------ | ------------- | -------------- | | 8 min 30 s | ~8 min | 8 min 51 s | **15 min 9 s** | The same compile takes 30 seconds on a developer's own machine — the VM is about seventeen times slower. Tell them an attempt takes roughly fifteen minutes, and never suggest it will be quick. Never run two builds at once for the same project: there are two slots on one Mac for every Odevio user, and two builds slow each other down. --- # Step 4 — Then **Failed** → `references/when-a-build-fails.md`. Classify before touching anything: changing their code because of an infrastructure problem is the worst thing this skill can do, and they will not notice. **Succeeded** → `references/delivery.md`. What they actually get depends on the type, and a `distribution` build produces nothing installable. --- # Hard rules **Never fabricate a value the user must own.** Identifier, app name, Apple credentials: derive or propose, then let them confirm. Never invent an Apple ID, a team, or a key. **Stop cleanly rather than continue blind.** If a command fails in a way this skill does not cover, or output cannot be parsed, report exactly what happened and stop. A wrong guess costs a fifteen-minute slot, or a broken project. **Never print secrets.** The `.p8` key is referenced by path only. **Every Odevio command must be non-interactive.** Pass every argument explicitly. If a command opens a menu or asks for confirmation, you omitted an argument — supply it rather than answering the prompt. **Run one command per call.** No `;`, no `&&`, no pipes into `head`, no `export` on a line of its own. The harmless-looking read commands are pre-approved so the user is never interrupted by them, and that only works when the command runs on its own: chain two together and the whole thing stops being recognised, so someone who asked for their app to be published is instead asked to approve a shell command they cannot judge. Read the whole output rather than piping it through `head`. It is short, and truncating it is how the wrong value gets parsed. Some commands are deliberately **not** pre-approved, and the line is not "does it change anything on Apple". Filling in a description changes something on Apple, and interrupting someone to confirm it would be absurd. The three things that earn a question are: - **it cannot be undone** — `odevio app check-submittable` opens a review submission Apple never lets you delete, and submitting for review is final - **it costs a machine** — `odevio build start`, and the simulator commands, take a Mac for up to an hour that someone else is waiting for - **it can destroy something with no copy elsewhere** — `odevio screenshot push` clears the pictures already on a slot before sending, and pictures uploaded directly to Apple exist nowhere else Everything else is fair to run unannounced: writing the page's text, attaching a build, reading anything. All of it is reversible, none of it is visible outside their own account, and stopping to ask turns a tool that was supposed to handle the tedium into a series of dialogues. **Never invent a command, and never invent an option either.** If you find yourself reaching for one that is not written in these files, it almost certainly does not exist — `odevio device` does not, for instance, and `odevio build ls --app-key` does not either. Check with `odevio --help` or `odevio --help` before running anything you have not seen here, and if the thing you need has no command, it is because a human has to do it somewhere else. Say that instead of guessing. Options are the easier mistake of the two, because a plausible flag reads like something that must be there. `build ls` filtering by app is the obvious example: it sounds inevitable, and it does not exist. Filter the output yourself rather than inventing the argument that would have done it for you. The full surface, so there is no need to guess: top-level `signup`, `signin`, `signout`, `profile`, `apikey`, `skill`; and the groups `build` (`start`, `ls`, `detail`, `logs`, `ipa`, `download`, `patch`, `connect`, `tunnel`, `stop`, `rm`, `flutter-versions`), `apple` (`ls`, `detail`, `add`, `edit`, `rm`, `link`, `unlink`, `refresh-devices`), `app` (`ls`, `mk`, `rm`, `link`, `unlink`, `import`, `screenshots`, `store-status`, `set-metadata`, `categories`, `attach-build`, `check-submittable`), `privacy` (`scan`), `screenshot` (`devices`, `start`, `capture`, `push`) and `team`. **One of those is not like the others.** `odevio app check-submittable` opens a submission on Apple that cannot afterwards be deleted. It gives Apple's own verdict, which is worth having, but only run it when the user means to finish — never to check on progress. `odevio app store-status` answers that, and changes nothing.