Skip to content
Akedly

Log in and manage CLI Logins

akedly login ties your terminal to your Akedly account. You approve it once in the dashboard. After that the CLI acts as you, with the access level you chose.

Build with AI agents

Start a login

  1. Run akedly login.

    Add --ksa to log in to the KSA deployment. The CLI asks the server for a login request and prints Approve code <code> at <url>. In JSON mode it writes an approval_required event to stderr instead (progress events).

    While customer CLI access is turned off on the server, the request is refused straight away with CLI_DISABLED (exit 70). No code is printed and there is nothing to approve; try again later.

  2. Open the link and approve.

    Open the link in a browser where you are signed in to the dashboard, check that the code matches your terminal, then approve. The request lasts 10 minutes. A code with less than 10 seconds left cannot be approved: the server answers HTTP 410 CLI_LOGIN_REQUEST_EXPIRED, the page shows This code has expired, and you run akedly login again for a new code.

  3. Wait for the terminal.

    The CLI checks for your decision every 5 seconds. If the server rate-limits the checks, the CLI slows to the pace it asks for and keeps waiting; it does not stop with exit 69. When you approve, it saves the login and prints who you are signed in as. Otherwise it stops with one of these codes, all with exit status 1:

    • LOGIN_TIMEOUT: the wait ended without a decision. The CLI stops waiting at whichever comes first, the --timeout deadline or the expiry time the server gave the login request.
    • CLI_LOGIN_REQUEST_EXPIRED: a check for your decision came back with that server error.
    • CLI_LOGIN_DENIED: a check for your decision reported that the request was denied.
    • CLI_SECRET_ALREADY_DELIVERED: the request was approved, but its credential was already handed out to an earlier check. This happens when the terminal lost the response, for example after a network drop or a crash. The credential cannot be sent again, so this login is stranded.

    The hint for each code says to run akedly login again. To recover a stranded login, start a new akedly login and approve the new code. The stranded login still counts toward your active logins until it expires; end it with akedly cli-logins list and akedly cli-logins end <id>.

    When the login is saved, the result names where the credential is stored: credentialStorage.mode is file and credentialStorage.path is the credentials file (where the CLI keeps credentials).

Login flags

  • Name
    --open
    Type
    boolean
    Description

    Also opens the link in your default browser. This is best effort: if the browser cannot be opened, the CLI prints Could not open the browser. Open the approval URL yourself. to stderr (in JSON mode, an open_failed event) and keeps waiting.

  • Name
    --timeout
    Type
    seconds
    Description

    How long to wait for approval. Defaults to 600. The wait also ends when the login request expires.

  • Name
    --machine-name
    Type
    text
    Description

    The machine name shown on the approval page, up to 60 characters. It is also the starting value of the page's Login name field. Defaults to this machine's hostname, or terminal if that is empty.

  • Name
    --ksa
    Type
    boolean
    Description

    Logs in to the KSA deployment.

  • Name
    --dry-run
    Type
    boolean
    Description

    Prints the request the CLI would send and contacts nothing.

What you approve

The approval page, Approve CLI login, shows the request before you decide:

  • Name
    Login code
    Description

    The code from your terminal. Approve only a code you started yourself.

  • Name
    Machine
    Description

    The machine name from --machine-name or the hostname.

  • Name
    CLI version
    Description

    The version of the CLI that asked.

  • Name
    Requested and Code expires
    Description

    When the request was made and when this code expires. This is not how long the login lasts; you choose that under Stay signed in for.

  • Name
    Organization
    Description

    The organization the login acts in, or Personal account. If your account has an organization menu in the dashboard header, use it to switch organizations; this page then reloads the request for that organization.

  • Name
    Login name
    Description

    The name this login gets on the CLI Logins page. It starts as the machine name. You can change it here, up to 60 characters.

  • Name
    Access level
    Description

    Full access or Read-only (below).

  • Name
    Stay signed in for
    Description

    1, 7 or 30 days (below).

Access levelWhat the CLI can do
Full accessEverything your role allows.
Read-onlyCommands that use this login can view data but cannot change your setup or send messages; those requests are refused with CLI_READ_ONLY (exit 67). This applies to owners too. It can still mark announcements and reports as seen or opened and rate a report's AI summary, because those only record your own viewing.
Warning:

Read-only limits this login, not your API keys

The access level applies only to requests made with this CLI Login's credential. The five Sending Commands, otp v1 create, otp v1.2 challenge, otp v1.2 send, otp v2 attempt and transactions status, use an API key instead, so a Read-only login does not stop them. Whoever holds an API key can run them, within that key's own scope and budget. To keep a person or agent from sending, do not give them an API key.

Then choose Approve login or Deny login. Denying the request makes the terminal stop with CLI_LOGIN_DENIED (exit 1) when it receives that decision. Codes expire 10 minutes after the request is created; run akedly login again for a new one.

Akedly staff can approve or deny a code for your account only from a full-access staff session. A restricted staff session is refused with IMPERSONATION_BLOCKED (HTTP 403). A login that staff approve ends when their staff session ends.

How long a login lasts

  • Name
    Stay signed in for
    Description

    1, 7 or 30 days, chosen on the approval page. 30 days is the default.

  • Name
    Active logins
    Description

    The normal approval limit is 10 active CLI Logins per person per account. Approved requests whose credentials have not yet been collected also count toward the limit.

  • Name
    Role and team changes
    Description

    Can take up to 60 seconds to reach a CLI Login that is already signed in.

  • Name
    Ending a login
    Description

    Takes effect the next time the credential is used. Leaving the team can take up to about 60 seconds to reach it. A later command then fails with LOGIN_REQUIRED (exit 66).

  • Name
    Expiry warning
    Description

    Within 3 days of the end date, the CLI prints a warning to stderr. Run akedly login to renew.

  • Name
    Records
    Description

    A login record becomes eligible for automatic deletion 90 days after it ends or expires. Cleanup may happen later.

Replacing a login

Running akedly login again in the same region saves the new login first, then tries to end the previous one stored for that region. That last step is best effort. A login supplied through AKEDLY_CLI_LOGIN is never ended this way.

AKEDLY_CLI_LOGIN still wins over the stored login. If it is set when akedly login finishes, the CLI saves the new login and then prints AKEDLY_CLI_LOGIN is set, so commands keep using that login until you unset it. to stderr (in JSON mode, an env_login_active event). Unset the variable to use the new login.

See and end CLI Logins

CLI Logins

akedly cli-logins list
akedly cli-logins end <id>
akedly cli-logins team list
akedly cli-logins team end <id> --yes
  • cli-logins list and cli-logins end cover your own logins.
  • cli-logins team list and cli-logins team end cover your organization's logins and are for team admins. Ending a teammate's login needs --yes.
  • A Read-only login can list and log out. To end another login, use a Full access login.

In the dashboard, the same list is on the CLI logins page, /admin/cli-logins.

Sign out

Sign out

akedly logout
akedly logout --ksa

akedly logout ends the CLI Login on the server and removes it from this machine. If the login had already ended, the CLI removes the local copy and says so. Saved API keys stay. If AKEDLY_CLI_LOGIN is set, unset it yourself; the CLI reminds you.

Headless machines and CI

The CLI reads these environment variables:

  • Name
    AKEDLY_CLI_LOGIN
    Type
    secret
    Description

    A CLI Login credential. It overrides the login stored on this machine. It is not tied to a region: set AKEDLY_REGION=ksa, or pass --ksa, when it was issued by the KSA dashboard. Never put it in prompts or logs.

  • Name
    AKEDLY_API_KEY
    Type
    secret
    Description

    A full API key, used only by Sending Commands. Never pass a key on the command line.

  • Name
    AKEDLY_OUTPUT
    Type
    json | human
    Description

    The output mode.

  • Name
    AKEDLY_REGION
    Type
    egypt | ksa
    Description

    The region. Set it with AKEDLY_CLI_LOGIN for a KSA login.

  • Name
    AKEDLY_CONFIG_DIR
    Type
    path
    Description

    Where the CLI keeps its configuration. Use a directory that holds nothing else.

  • Name
    XDG_CONFIG_HOME
    Type
    path
    Description

    If AKEDLY_CONFIG_DIR is not set, the configuration goes in $XDG_CONFIG_HOME/akedly.

  • Name
    AKEDLY_API_URL
    Type
    URL
    Description

    Overrides the API base URL for either region. Requests, including credentials sent in headers or request bodies, go to this address. Use only a server you trust. HTTPS is required except for HTTP on loopback development hosts. End it with the API base path, normally /api/v1. A proxy path before it, as in https://proxy.example.com/akedly/api/v1, is kept on every request.

  • Name
    AKEDLY_APP_URL
    Type
    URL
    Description

    Overrides the dashboard base URL used for browser hand-offs. When AKEDLY_API_URL is set without this variable, dashboard hand-offs omit the full URL. This does not replace the approval URL returned by the login server.

  • Name
    AKEDLY_WEBHOOK_SECRET
    Type
    secret
    Description

    Supplies the pipeline webhook signing secret for local akedly webhooks verify. --secret-file takes precedence. Keep the secret out of prompts, logs and command arguments.

  • Name
    AKEDLY_WIDGET_SECRET
    Type
    secret
    Description

    Supplies the widget Secret used to sign akedly otp v2 attempt. --widget-secret-file takes precedence. This is separate from the API key. Keep it out of prompts, logs and command arguments.

With neither variable set, the configuration lives in ~/.config/akedly. The CLI creates the folder private to your user (mode 0700). If the folder already exists and is open to other users, the CLI warns you and does not change it; run chmod 700 on it yourself.

Login and API-key secrets are stored in plaintext files in that folder, mode 0600: credentials.json for CLI Logins and api-keys.json for saved API keys. Anyone who can read these files can act as you, so keep the folder private and do not copy it. akedly login and akedly doctor report where the CLI Login is stored: the storage mode and the file path.

What a CLI Login is

Note:

A CLI Login is not an API key

A CLI Login is one person's approved, revocable permission for one CLI on one machine to act as that person in one organization, with an access level and an end date. You approve it in the browser. It ends when you log out, when you, a team admin or Akedly staff end it, when it expires, when you leave the team, or when the account is deleted. A login that Akedly staff approved for your account also ends when their staff session ends. An ending takes effect the next time the credential is used, not at the moment of the change; leaving the team can take up to about 60 seconds to reach it.

Sending Commands, the commands that call the public OTP APIs, never use it: they use an API key, as your own code would.