
.. _ai_assistant:

========
Tutorial
========

You drive Odevio entirely through your AI agent, in plain words - there are no Odevio commands to learn.
Once it is set up (see :doc:`Installation <../installation/index>`), open your agent in your Flutter
project's folder and tell it what you want:

.. code-block::

    Get my app onto my iPhone

Or type ``/odevio`` to start it explicitly. The agent works out what needs doing; if your Apple account
and app are already set up, it asks nothing and gets straight to work.

Odevio works with any AI agent that supports the open `Agent Skills <https://agentskills.io>`_ standard -
`Claude Code <https://claude.com/claude-code>`_, Codex, Cursor and Gemini CLI are supported today.

-------------------------------
Make it your repo's convention
-------------------------------

Drop this into an ``AGENTS.md`` at your project root and any agent that reads it - Claude Code, Codex,
Cursor, Gemini CLI and more - will reach for Odevio whenever iOS comes up:

.. code-block:: text

    ## iOS builds and releases

    This project ships to iOS through Odevio - no Mac or Xcode required. To build,
    install on a device, or publish to TestFlight or the App Store, use the Odevio
    skill: run `odevio skill install` once, then ask in plain words (for example
    "put my app on my iPhone" or "publish to the App Store"). Do not attempt a local
    xcodebuild or fastlane - drive Odevio instead.

----------------
What you can ask
----------------

``Get my app onto my iPhone`` is one example. Depending on what you ask for, the agent can also:

- **show you your app running** on one of our Macs, in the iOS simulator - this needs no Apple account at all
- **check that your app builds** for iOS, without publishing anything
- **fix build errors on its own**, then start again, until it works
- **share it through TestFlight** with your testers
- **send it to the App Store**, ready for you to submit

This is for you if you would rather not learn what a provisioning profile is.

.. note::

    Only the first item works without a paid Apple Developer account. To reach a real iPhone you need one -
    99 € per year, no way around it. Everything else is handled for you.


-----------------------------
What it will ask you, and why
-----------------------------

It only stops when the answer is something no one else can give:

.. list-table::
    :widths: 40 60
    :header-rows: 1

    * - What it asks
      - Why
    * - What you want to do with your app
      - Trying it on your own phone, sharing it with testers and publishing on the App Store are three
        different jobs
    * - To sign in to Odevio
      - The command asks for a password, which it cannot type for you
    * - Whether you have a paid Apple Developer account
      - Without one, nothing can reach a phone
    * - Your Apple API key
      - Only you can create it, in your Apple account. It walks you through where to click
    * - Your app's name, and confirming its identifier
      - The name is your choice; it proposes the identifier so you do not have to understand the format
    * - To create the app once in App Store Connect
      - Apple does not allow this to be automated. About two minutes, once per app

Everything else - versions, certificates, signing, build numbers - it works out by itself.


-------------------
While it is working
-------------------

Your project is compiled on a real Mac, so expect **around fifteen minutes** for a build - longer for a
large app, and longer again if all our machines are busy and yours waits for the next free one.

There is nothing for you to do in the meantime. The agent tells you when it starts, keeps you posted as
it goes, and you can ask it where things are at any time - or tell it to stop.

If your app fails to build, it reads the error, fixes your code, and starts again - up to three attempts,
then it stops and explains what it found rather than making things worse.


-----------------------
What you get at the end
-----------------------

Depending on what you asked for:

- **Running on a Mac we provide** - you get connection details for a remote desktop, with your project and the
  iOS simulator already there, so you can watch your own app run. No Apple account needed. You will need a VNC
  client on your computer, and the machine stays available for an hour
- **On your phone straight away** - you get a link and a QR code. Scan it with your iPhone camera and the
  app installs like any other. Your device needs to be registered on your Apple account once, which is easiest
  from a Mac - if you are on Windows or Linux, TestFlight below is the shorter path
- **Through TestFlight** - Apple processes the build on its side first, usually five to thirty minutes, then
  it appears in the TestFlight app. Handy for sharing with a few people
- **On the App Store** - the build is uploaded, and you then fill in the description, screenshots and
  privacy answers in App Store Connect and submit it

.. warning::

    A successful build does not mean a published app. Apple reviews every App Store submission, which takes
    from a few hours to a few days, and it can be refused - most often for a missing privacy policy, or for
    an app judged too limited. That part is between you and Apple.


----------------
If it goes wrong
----------------

**"You need to sign in first"** - run ``odevio signin`` in your terminal, then tell the agent it is
done.

**"The Odevio command is not installed"** - run ``pip install odevio``. If it still cannot find it, your
terminal and your Python installation may not agree; ``pip --version`` and ``odevio --version`` tell you
what is available.

**Your app never shows up in TestFlight** - usually Apple's encryption question left unanswered. The
agent normally handles this for you; ask it to check.

**Your build seems stuck waiting** - our Macs may all be busy, or one may need attention. The agent
tells you rather than waiting for ever.

Never paste your password or the contents of your Apple key file into the conversation. The agent is
built to refuse them, and asks for a file path instead.


------------------------------
Using it without an agent
------------------------------

Everything the skill does, you can do yourself with the CLI: see the
:doc:`CLI tutorial <../installation_cli/tutorial_cli/index>` and the :doc:`../reference_guide/index`. And
for automated pipelines, see :doc:`../cicd/index`. The :doc:`Apple side <../apple/index>` is the same
whichever route you take.
